diff --git a/cookbook/en.txt b/cookbook/en.txt index 7240ec98d..e7ee1629b 100644 --- a/cookbook/en.txt +++ b/cookbook/en.txt @@ -1,6 +1,6 @@ + Getting Started XML-Edition + Implementing ArrayAccess for domain objects -+ Implementing the NOTIFY changetracking policy ++ Implementing the NOTIFY change-tracking policy + Validation of Entities + Implementing wakeup or clone + Integrating with CodeIgniter diff --git a/cookbook/en/aggregate-fields.txt b/cookbook/en/aggregate-fields.txt index 0dc5d18d7..18e445034 100644 --- a/cookbook/en/aggregate-fields.txt +++ b/cookbook/en/aggregate-fields.txt @@ -248,11 +248,11 @@ code in `Account::getBalance()` and `Account:addEntry()`: } This is a very simple change, but all the tests still pass. Our account entities return -the correct balance. Now calling the `Account::getBalance()` method will not occour the +the correct balance. Now calling the `Account::getBalance()` method will not occur the overhead of loading all entries anymore. Adding a new Entry to the `Account::$entities` will also not initialize the collection internally. -Adding a new entry is therefore very performant and explictly hooked into the domain model. +Adding a new entry is therefore very performant and explicitly hooked into the domain model. It will only update the account with the current balance and insert the new entry into the database. ## Tackling Race Conditions with Aggregate Fields @@ -293,7 +293,7 @@ Optimistic locking is as easy as adding a version column: The previous example would then throw an exception in the face of whatever request saves the entity last (and would create the inconsistent state). -Pessimmistic locking requires an additional flag set on the `EntityManager::find()` +Pessimistic locking requires an additional flag set on the `EntityManager::find()` call, enabling write locking directly in the database using a FOR UPDATE. [php] diff --git a/cookbook/en/dql-custom-walkers.txt b/cookbook/en/dql-custom-walkers.txt index 48d4840a4..2f314cd78 100644 --- a/cookbook/en/dql-custom-walkers.txt +++ b/cookbook/en/dql-custom-walkers.txt @@ -1,13 +1,13 @@ # Extending DQL in Doctrine 2: Custom AST Walkers -The Doctrine Query Language (DQL) is a propriotary sql-dialect that substitutes +The Doctrine Query Language (DQL) is a proprietary sql-dialect that substitutes tables and columns for Entity names and their fields. Using DQL you write a query against the database using your entities. With the help of the metadata you can write very concise, compact and powerful queries that are then translated into SQL by the Doctrine ORM. In Doctrine 1 the DQL language was not implemented using a real parser. This -made modifications of the DQL by the user impossible. Doctrine 2 in constrast +made modifications of the DQL by the user impossible. Doctrine 2 in contrast has a real parser for the DQL language, which transforms the DQL statement into an [Abstract Syntax Tree](http://en.wikipedia.org/wiki/Abstract_syntax_tree) and generates the appropriate SQL statement for it. Since this process is @@ -130,7 +130,7 @@ execution plans. You can write your own output walker to introduce certain keywords using the Query Hint API. A query hint can be set via `Query::setHint($name, $value)` as shown in the previous example with the `HINT_CUSTOM_TREE_WALKERS` query hint. -We will implement a custom Output Walker that allows to specifiy the SQL_NO_CACHE +We will implement a custom Output Walker that allows to specify the SQL_NO_CACHE query hint. [php] diff --git a/cookbook/en/dql-user-defined-functions.txt b/cookbook/en/dql-user-defined-functions.txt index d738617c4..811a5cf36 100644 --- a/cookbook/en/dql-user-defined-functions.txt +++ b/cookbook/en/dql-user-defined-functions.txt @@ -48,7 +48,7 @@ takes two dates as argument and calculates the difference in days with `date1-da The DQL parser is a top-down recursive descent parser to generate the Abstract-Syntax Tree (AST) and uses a TreeWalker approach to generate the appropriate -SQL from the AST. This makes reading the Parser/TreeWalker code managable +SQL from the AST. This makes reading the Parser/TreeWalker code manageable in a finite amount of time. The `FunctionNode` class I referred to earlier requires you to implement @@ -98,13 +98,13 @@ to the generation of a DateDiff FunctionNode somewhere in the AST of the dql statement. The `ArithmeticPrimary` method call is the most common denominator of valid -EBNF tokens taken from the [DQL EBNF grammer](http://www.doctrine-project.org/documentation/manual/2_0/en/dql-doctrine-query-language#ebnf) +EBNF tokens taken from the [DQL EBNF grammar](http://www.doctrine-project.org/documentation/manual/2_0/en/dql-doctrine-query-language#ebnf) that matches our requirements for valid input into the DateDiff Dql function. Picking the right tokens for your methods is a tricky business, but the EBNF -grammer is pretty helpful finding it, as is looking at the Parser source code. +grammar is pretty helpful finding it, as is looking at the Parser source code. Now in the TreeWalker process we have to pick up this node and generate SQL -from it, which apprently is quite easy looking at the code in (7). Since +from it, which apparently is quite easy looking at the code in (7). Since we don't know which type of AST Node the first and second Date expression are we are just dispatching them back to the SQL Walker to generate SQL from and then wrap our DATEDIFF function call around this output. @@ -125,7 +125,7 @@ We can do fancy stuff like: Often useful it the ability to do some simple date calculations in your DQL query using [MySql's DATE_ADD function](http://dev.mysql.com/doc/refman/5.1/en/date-and-time-functions.html#function_date-add). -I'll skip the bla and show the code for this function: +I'll skip the blah and show the code for this function: [php] /** @@ -176,7 +176,7 @@ the value of the `T_IDENTIFIER` token for the Date Interval unit, for example th The above method now only supports the specification using `INTERVAL`, to also allow a real date in DATE_ADD we need to add some decision logic to the parsing -process (makes up for a nice excercise). +process (makes up for a nice exercise). Now as you see, the Parsing process doesn't catch all the possible SQL errors, here we don't match for all the valid inputs for the interval unit. diff --git a/cookbook/en/getting-started-xml-edition.txt b/cookbook/en/getting-started-xml-edition.txt index f78834064..74e637b0c 100644 --- a/cookbook/en/getting-started-xml-edition.txt +++ b/cookbook/en/getting-started-xml-edition.txt @@ -1,13 +1,13 @@ Doctrine 2 is a project that aims to handle the persistence of the domain model in a non-interfering way. The Data Mapper pattern is at the heart of this project, aiming for a complete separation of the domain/business logic from the persistence in a relational database management system. The benefit of Doctrine for the programmer is the -possibility can focus soley on the business and worry about persistence only as a secondary task. This doesn't mean +possibility can focus solely on the business and worry about persistence only as a secondary task. This doesn't mean persistence is not important to Doctrine 2, however it is our belief that there are considerable benefits for object-oriented -programming, if persistence and entities are kept perfectly seperated. +programming, if persistence and entities are kept perfectly separated. ## What are Entities? -Entities are leightweight PHP Objects that don't need to extend any abstract base class or interface. +Entities are lightweight PHP Objects that don't need to extend any abstract base class or interface. An entity class must not be final or contain final methods. Additionally it must not implement __clone nor __wakeup or [do so safely](http://www.doctrine-project.org/documentation/cookbook/2_0/en/implementing-wakeup-or-clone). @@ -20,7 +20,7 @@ For this Getting Started Guide for Doctrine we will implement the Bug Tracker do documentation. Reading their documentation we can extract the requirements to be: * A Bugs has a description, creation date, status, reporter and engineer -* A bug can occour on different products (platforms) +* A bug can occur on different products (platforms) * Products have a name. * Bug Reporter and Engineers are both Users of the System. * A user can create new bugs. @@ -69,7 +69,7 @@ A first simplified design for this domain model might look like the following se > public properties can make up for pretty nasty bugs. Because we will focus on the mapping aspect, no effort is being made to encapsulate the business logic in this example. -All peristable properties are public in visibility. We will soon see that this is not the best solution in combination +All persistable properties are public in visibility. We will soon see that this is not the best solution in combination with Doctrine 2, one restriction that actually forces you to encapsulate your properties. For persistence Doctrine 2 actually uses Reflection to access the values in all your entities properties. @@ -121,24 +121,24 @@ Now that we know this, we have to clear up our domain model to cope with the ass Whenever an entity is recreated from the database, an Collection implementation of the type Doctrine\ORM\PersistantCollection is injected into your entity instead of an array. Compared to the ArrayCollection this implementation helps the Doctrine ORM understand the changes that -have happend to the collection which are noteworthy for persistence. +have happened to the collection which are noteworthy for persistence. > **Warning** > Lazy load proxies always contain an instance of Doctrine's EntityManager and all its dependencies. Therefore a var_dump() > will possibly dump a very large recursive structure which is impossible to render and read. You have to use > `Doctrine\Common\Util\Debug::dump()` to restrict the dumping to a human readable level. Additionally you should be aware > that dumping the EntityManager to a Browser may take several minutes, and the Debug::dump() method just ignores any -> occurences of it in Proxy instances. +> occurrences of it in Proxy instances. Because we only work with collections for the references we must be careful to implement a bidirectional reference in the domain model. The concept of owning or inverse side of a relation is central to this notion and should always be kept in mind. The following assumptions are made about relations and have to be followed to be able to work with Doctrine 2. These assumptions are not unique to Doctrine 2 but are best practices in handling database relations and Object-Relational Mapping. -* Changes to Collections are saved or updated, when the entity on the *ownin*g side of the collection is saved or updated. +* Changes to Collections are saved or updated, when the entity on the *owning* side of the collection is saved or updated. * Saving an Entity at the inverse side of a relation never triggers a persist operation to changes to the collection. * In a one-to-one relation the entity holding the foreign key of the related entity on its own database table is *always* the owning side of the relation. -* In a many-to-many relation, both sides can be the owning side of the relation. However in a bi-directional many-tomany relation only one is allowed to be. +* In a many-to-many relation, both sides can be the owning side of the relation. However in a bi-directional many-to-many relation only one is allowed to be. * In a many-to-one relation the Many-side is the owning side by default, because it holds the foreign key. * The OneToMany side of a relation is inverse by default, since the foreign key is saved on the Many side. A OneToMany relation can only be the owning side, if its implemented using a ManyToMany relation with join table and restricting the one side to allow only UNIQUE values per database constraint. @@ -236,13 +236,13 @@ object-oriented best-practices. ## Metadata Mappings for our Entities -Up to now we have only implemented our Entites as Data-Structures without actually telling Doctrine how to persist +Up to now we have only implemented our Entities as Data-Structures without actually telling Doctrine how to persist them in the database. If perfect in-memory databases would exist, we could now finish the application using these entities -by implementing code to fullfil all the requirements. However the world isn't perfect and we have to persist our +by implementing code to fulfil all the requirements. However the world isn't perfect and we have to persist our entities in some storage to make sure we don't loose their state. Doctrine currently serves Relational Database Management Systems. In the future we are thinking to support NoSQL vendors like CouchDb or MongoDb, however this is still far in the future. -The next step for persistance with Doctrine is to describe the structure of our domain model entities to Doctrine +The next step for persistence with Doctrine is to describe the structure of our domain model entities to Doctrine using a metadata language. The metadata language describes how entities, their properties and references should be persisted and what constraints should be applied to them. @@ -272,7 +272,7 @@ The first discussed definition will be for the Product, since it is the most sim -The toplevel `entity` definition tag specifies information about the class and table-name. The +The top-level `entity` definition tag specifies information about the class and table-name. The primitive type `Product::$name` is defined as `field` attributes. The Id property is defined with the `id` tag. The id has a `generator` tag nested inside which defines that the primary key generation mechanism automatically uses the database platforms native id generation strategy, for example AUTO INCREMENT @@ -325,14 +325,14 @@ which translates the YYYY-mm-dd HH:mm:ss Database format into a PHP DateTime ins After the field definitions the two qualified references to the user entity are defined. They are created by the `many-to-one` tag. The class name of the related entity has to be specified with the `target-entity` attribute, which is enough information for the database mapper to access the foreign-table. The -`join-column` tags are used to specifiy how the foreign and referend columns are named, an information +`join-column` tags are used to specify how the foreign and referenced columns are named, an information Doctrine needs to construct joins between those two entities correctly. Since `reporter` and `engineer` -are on the owning side of a bi-direcitonal relation we also have to specify the `inversed-by` attribute. +are on the owning side of a bi-directional relation we also have to specify the `inversed-by` attribute. They have to point to the field names on the inverse side of the relationship. The last missing property is the `Bug::$products` collection. It holds all products where the specific -bug is occouring in. Again you have to define the `target-entity` and `field` attributes on the `many-to-many` -tag. Furthermore you have to specifiy the details of the many-to-many join-table and its foreign key columns. +bug is occurring in. Again you have to define the `target-entity` and `field` attributes on the `many-to-many` +tag. Furthermore you have to specify the details of the many-to-many join-table and its foreign key columns. The definition is rather complex, however relying on the XML auto-completion I got it working easily, although I forget the schema details all the time. @@ -390,8 +390,8 @@ steps and then discuss them step by step: $config->setMetadataDriverImpl($driverImpl); // Caching Configuration (5) - if (APPLICATION_ENV == "develoment") { - $cache = new \Doctrine\Common\Cache\ArayCache(); + if (APPLICATION_ENV == "development") { + $cache = new \Doctrine\Common\Cache\ArrayCache(); } else { $cache = new \Doctrine\Common\Cache\ApcCache(); } @@ -409,7 +409,7 @@ steps and then discuss them step by step: $entityManager = \Doctrine\ORM\EntityManager::create($conn, $config, $evm); The first block sets up the autoloading capabilities of Doctrine. I am registering the Doctrine -namespace to the given path. To add your own namespace you can instantiate another `CloassLoader` +namespace to the given path. To add your own namespace you can instantiate another `ClassLoader` with different namespace and path arguments. There is no requirement to use the Doctrine `ClassLoader` for your autoloading needs, you can use whatever suits you best. @@ -417,10 +417,10 @@ The second block contains of the instantiation of the ORM Configuration object. configuration shown in the next blocks there are several others with are all explained in the [Configuration section of the manual](http://www.doctrine-project.org/documentation/manual/2_0/en/configuration#configuration-options). -The Proxy Configuration is a required block for your application, you have to specifiy where +The Proxy Configuration is a required block for your application, you have to specify where Doctrine writes the PHP code for Proxy Generation. Proxies are children of your entities generated by Doctrine to allow for type-safe lazy loading. We will see in a later chapter how exactly this works. -Besides the path to the proxies we also specifiy which namespace they will reside under aswell as +Besides the path to the proxies we also specify which namespace they will reside under as well as a flag `autoGenerateProxyClasses` indicating that proxies should be re-generated on each request, which is recommended for development. In production this should be prevented at all costs, the proxy class generation can be quite costly. @@ -449,7 +449,7 @@ we want to generate the relational database schema from it. Doctrine has a Command-Line-Interface that allows you to access the SchemaTool, a component that generates the required tables to work with the metadata. -For the commandline tool to work a cli-config.php file has to be present in the project root directry, +For the command-line tool to work a cli-config.php file has to be present in the project root directory, where you will execute the doctrine command. Its a fairly simple file: [php] @@ -458,7 +458,7 @@ where you will execute the doctrine command. Its a fairly simple file: )); $cli->setHelperSet($helperSet); -You can then change into your project directory and call the Doctrine commandline tool: +You can then change into your project directory and call the Doctrine command-line tool: [console] doctrine@my-desktop> cd myproject/ @@ -468,7 +468,7 @@ You can then change into your project directory and call the Doctrine commandlin > > The `doctrine` command will only be present if you installed Doctrine from PEAR. > Otherwise you will have to dig into the `bin/doctrine.php` code of your Doctrine 2 -> directory to setup your doctrine commandline client. +> directory to setup your doctrine command-line client. > > See the [Tools section of the manual](http://www.doctrine-project.org/projects/orm/2.0/docs/reference/tools/en) > on how to setup the Doctrine console correctly. @@ -478,7 +478,7 @@ metadata. You can then either re-create the database: [console] doctrine@my-desktop> doctrine orm:schema-tool:drop - doctrine@my-dekstop> doctrine orm:schema-tool:create + doctrine@my-desktop> doctrine orm:schema-tool:create Or use the update functionality: @@ -609,7 +609,7 @@ in one single SQL statement. The console output of this script is then: > and powerful queries. > > An important reason why DQL is favourable to the Query API of most ORMs is its similarity to SQL. The DQL language -> allows query constructs that most ORMs don't, GROUP BY even with HAVING, Subselects, Fetch-Joins of nested +> allows query constructs that most ORMs don't, GROUP BY even with HAVING, Sub-selects, Fetch-Joins of nested > classes, mixed results with entities and scalar data such as COUNT() results and much more. Using > DQL you should seldom come to the point where you want to throw your ORM into the dumpster, because it > doesn't support some the more powerful SQL concepts. @@ -625,9 +625,9 @@ in one single SQL statement. The console output of this script is then: ### Array Hydration of the Bug List In the previous use-case we retrieved the result as their respective object instances. -We are not limitied to retrieving objects only from Doctrine however. For a simple list view +We are not limited to retrieving objects only from Doctrine however. For a simple list view like the previous one we only need read access to our entities and can switch the hydration -from objects to simple PHP arrays instead. This can obviously yiel considerable performance benefits for read-only requests. +from objects to simple PHP arrays instead. This can obviously yield considerable performance benefits for read-only requests. Implementing the same list view as before using array hydration we can rewrite our code: @@ -667,7 +667,7 @@ However we will soon see another problem with our entities using this approach. echo "Bug: ".$bug->description."\n"; echo "Engineer: ".$bug->getEngineer()->name."\n"; -It will be null! What is happening? It worked in the previous example, so it can't be a problem with the persistance +It will be null! What is happening? It worked in the previous example, so it can't be a problem with the persistence code of Doctrine. What is it then? You walked in the public property trap. Since we only retrieved the bug by primary key both the engineer and reporter are not immediately loaded diff --git a/cookbook/en/implementing-the-notify-changetracking-policy.txt b/cookbook/en/implementing-the-notify-changetracking-policy.txt index 025375487..7c401e4dd 100644 --- a/cookbook/en/implementing-the-notify-changetracking-policy.txt +++ b/cookbook/en/implementing-the-notify-changetracking-policy.txt @@ -1,5 +1,5 @@ -The NOTIFY changetracking policy is the most effective changetracking policy provided by Doctrine but it requires some boilerplate code. This recipe will show you how this boilerplate code should look like. We will implement it on a [Layer Supertype](http://martinfowler.com/eaaCatalog/layerSupertype.html) for all our domain objects. +The NOTIFY change-tracking policy is the most effective change-tracking policy provided by Doctrine but it requires some boilerplate code. This recipe will show you how this boilerplate code should look like. We will implement it on a [Layer Supertype](http://martinfowler.com/eaaCatalog/layerSupertype.html) for all our domain objects. ++ Implementing NotifyPropertyChanged diff --git a/cookbook/en/strategy-cookbook-introduction.txt b/cookbook/en/strategy-cookbook-introduction.txt index 88c02a7da..18cd0fe58 100644 --- a/cookbook/en/strategy-cookbook-introduction.txt +++ b/cookbook/en/strategy-cookbook-introduction.txt @@ -13,15 +13,15 @@ Given a Content-Management-System, we probably want to add / edit some so-called So, in this scenario, when building your CMS, you will surely add lots of blocks and panels to your pages and you will find yourself highly uncomfortable because of the following: * Every existing page needs to know about the panels it contains - therefore, you'll have an association to your panels. But if you've got several types of panels - what do you do? Add an association to -every paneltype? This wouldn't be flexible. You might be tempted to add an AbstractPanelEntity and an AbstractBlockEntity that use class inheritance. Your page could then only confer to the AbstractPanelType and Doctrine 2 would do the rest for you, i.e. load the right entites. But - you'll for sure have lots of panels and blocks, and even worse, you'd have to edit the discriminator map *manually* every time you or another developer implements a new block / entity. This would tear down any effort of modular programming. +every panel-type? This wouldn't be flexible. You might be tempted to add an AbstractPanelEntity and an AbstractBlockEntity that use class inheritance. Your page could then only confer to the AbstractPanelType and Doctrine 2 would do the rest for you, i.e. load the right entities. But - you'll for sure have lots of panels and blocks, and even worse, you'd have to edit the discriminator map *manually* every time you or another developer implements a new block / entity. This would tear down any effort of modular programming. Therefore, we need something thats far more flexible. ++ Solution -The solution itself is pretty easy. We will have one base class that will be loaded via the page and that has specific behaviour - a Block class might render the frontend and even the backend, for example. Now, every block that you'll write might look different or need different data - therefore, we'll offer an API to these methods but internally, we use a strategy that exactly knows what to do. +The solution itself is pretty easy. We will have one base class that will be loaded via the page and that has specific behaviour - a Block class might render the front-end and even the backend, for example. Now, every block that you'll write might look different or need different data - therefore, we'll offer an API to these methods but internally, we use a strategy that exactly knows what to do. -First of all, we need to make sure that we have an interface that contains every needed action. Such actions would be rendering the frontend or the backend, solving dependencies (blocks that are supposed to be placed in the sidebar could refuse to be placed in the middle of your page, for example). +First of all, we need to make sure that we have an interface that contains every needed action. Such actions would be rendering the front-end or the backend, solving dependencies (blocks that are supposed to be placed in the sidebar could refuse to be placed in the middle of your page, for example). Such an interface could look like this: diff --git a/cookbook/en/validation-of-entities.txt b/cookbook/en/validation-of-entities.txt index 739a608d2..047fed22d 100644 --- a/cookbook/en/validation-of-entities.txt +++ b/cookbook/en/validation-of-entities.txt @@ -1,5 +1,5 @@ Doctrine 2 does not ship with any internal validators, the reason being that -we think all the frameworks out there already ship with quite decents ones that can be integrated +we think all the frameworks out there already ship with quite decent ones that can be integrated into your Domain easily. What we offer are hooks to execute any kind of validation. > **Note** @@ -7,7 +7,7 @@ into your Domain easily. What we offer are hooks to execute any kind of validati > one of many options. Of course you can also perform validations in value setters > or any other method of your entities that are used in your code. -Entities can register lifecycle evnt methods with Doctrine that are called on +Entities can register lifecycle event methods with Doctrine that are called on different occasions. For validation we would need to hook into the events called before persisting and updating. Even though we don't support validation out of the box, the implementation is even simpler than in Doctrine 1 @@ -71,7 +71,7 @@ this will happen before Beta 1 though. Now validation is performed whenever you call `EntityManager#persist($order)` or when you call `EntityManager#flush()` and an order is about to be updated. -Any Exception that happens in the lifecycle callbacks will be catched by the +Any Exception that happens in the lifecycle callbacks will be cached by the EntityManager and the current transaction is rolled back. Of course you can do any type of primitive checks, not null, email-validation, string size, @@ -105,7 +105,7 @@ Additionally there is no limitation in the number of methods you register on one particular event, i.e. you can register multiple methods for validation in "PrePersist" or "PreUpdate" or mix and share them in any combinations between those two events. -There is no limit to what you can and can't validate in "PrePersist" and "PreUpdate" aslong as +There is no limit to what you can and can't validate in "PrePersist" and "PreUpdate" as long as you don't create new entity instances. This was already discussed in the previous blog post on the Versionable extension, which requires another type of event called "onFlush". diff --git a/manual/en/annotations-reference.txt b/manual/en/annotations-reference.txt index fa154687a..37b035c0e 100644 --- a/manual/en/annotations-reference.txt +++ b/manual/en/annotations-reference.txt @@ -50,9 +50,9 @@ Optional attributes: * length - Used by the "string" type to determine its maximum length in the database. Doctrine does not validate the length of a string values for you. * precision - The precision for a decimal (exact numeric) column (Applies only for decimal column) * scale - The scale for a decimal (exact numeric) column (Applies only for decimal column) -* unique - Boolean value to determine if the value of the column should be unique accross all rows of the underlying entities table. +* unique - Boolean value to determine if the value of the column should be unique across all rows of the underlying entities table. * nullable - Determines if NULL values allowed for this column. -* columnDefinition - DDL SQL snippet that starts after the column name and specificies the complete (non-portable!) column definition. This attribute allows to make use of advanced RMDBS features. However you should make careful use of this feature and the consequences. Additionally you should remember that the "type" attribute still handles the conversion between PHP and Database values. If you use this attribute on a column that is used for joins between tables you should also take a look at [@JoinColumn](#ann_joincolumn). +* columnDefinition - DDL SQL snippet that starts after the column name and specifies the complete (non-portable!) column definition. This attribute allows to make use of advanced RMDBS features. However you should make careful use of this feature and the consequences. Additionally you should remember that the "type" attribute still handles the conversion between PHP and Database values. If you use this attribute on a column that is used for joins between tables you should also take a look at [@JoinColumn](#ann_joincolumn). Examples: @@ -76,7 +76,7 @@ Examples: +++ @ChangeTrackingPolicy The Change Tracking Policy annotation allows to specify how the Doctrine 2 UnitOfWork should detect changes -in properties of entities during flush. By default each entity is checked according to a deferred implict +in properties of entities during flush. By default each entity is checked according to a deferred implicit strategy, which means upon flush UnitOfWork compares all the properties of an entity to a previously stored snapshot. This works out of the box, however you might want to tweak the flush performance where using another change tracking policy is an interesting option. @@ -98,7 +98,7 @@ Example: +++ @DiscrimnatorColumn -This annotation is a required annotation for the topmost/super class of an inheritance hierachy. It specifies +This annotation is a required annotation for the topmost/super class of an inheritance hierarchy. It specifies the details of the column which saves the name of the class, which the entity is actually instantiated as. Required attributes: @@ -113,7 +113,7 @@ Optional attributes: +++ @DiscriminatorMap -The discrimnator map is a required annotation on the top-most/super class in an inheritance hierachy. It takes +The discriminator map is a required annotation on the top-most/super class in an inheritance hierarchy. It takes an array as only argument which defines which class should be saved under which name in the database. Keys are the database value and values are the classes, either as fully- or as unqualified class names depending if the classes are in the namespace or not. @@ -138,7 +138,7 @@ Required annotation to mark a PHP class as Entity. Doctrine manages the persiste Optional attributes: -* repositoryClass - Specifies the FQCN of a subclass of the Doctrine\ORM\EntityRepository. Use of repositories for entites is encouraged to keep specialized DQL and SQL operations separated from the Model/Domain Layer. +* repositoryClass - Specifies the FQCN of a subclass of the Doctrine\ORM\EntityRepository. Use of repositories for entities is encouraged to keep specialized DQL and SQL operations separated from the Model/Domain Layer. Example: @@ -222,7 +222,7 @@ Example: +++ @Id The annotated instance variable will be marked as entity identifier, the primary key in the database. -This annotation is a marker only and has no required or optional attributes. For entites that have multiple +This annotation is a marker only and has no required or optional attributes. For entities that have multiple identifier columns each column has to be marked with @Id. Example: @@ -237,7 +237,7 @@ Example: +++ @InheritanceType -In an inheritance hierachy you have to use this annotation on the topmost/super class to define which +In an inheritance hierarchy you have to use this annotation on the topmost/super class to define which strategy should be used for inheritance. Currently Single Table and Class Table Inheritance are supported. This annotation has always been used in conjunction with the [@DiscriminatorMap](#ann_discriminatormap) and @@ -273,7 +273,7 @@ Examples: This annotation is used in the context of relations in [@ManyToOne](#ann_manytoone), [@OneToOne](#ann_onetoone) fields and in the Context of [@JoinTable](#ann_jointable) nested inside a @ManyToMany. This annotation is not required. -If its not specified the attributes *name* and *referencedColumnName* are infered from the table and primary key names. +If its not specified the attributes *name* and *referencedColumnName* are inferred from the table and primary key names. Required attributes: @@ -286,7 +286,7 @@ Optional attributes: * nullable - Determine if the related entity is required, or if null is an allowed state for the relation. Defaults to true. * onDelete - Cascade Action (Database-level) * onUpdate - Cascade Action (Database-level) -* columnDefinition - DDL SQL snippet that starts after the column name and specificies the complete (non-portable!) column definition. This attribute allows to make use of advanced RMDBS features. Using this attribute on @JoinColumn is necessary if you need slightly different column definitions for joining columns, for example regarding NULL/NOT NULL defaults. However by default a "columnDefinition" attribute on [@Column](#ann_column) also sets the related @JoinColumn's columnDefinition. This is necessary to make foreign keys work. +* columnDefinition - DDL SQL snippet that starts after the column name and specifies the complete (non-portable!) column definition. This attribute allows to make use of advanced RMDBS features. Using this attribute on @JoinColumn is necessary if you need slightly different column definitions for joining columns, for example regarding NULL/NOT NULL defaults. However by default a "columnDefinition" attribute on [@Column](#ann_column) also sets the related @JoinColumn's columnDefinition. This is necessary to make foreign keys work. Example: @@ -306,14 +306,14 @@ with an entity that has multiple identifiers. +++ @JoinTable -Using [@OneToMany](#ann_onetomany) or [@ManyToMany](#ann_manytomany) on the owning side of the relation requires to specifiy +Using [@OneToMany](#ann_onetomany) or [@ManyToMany](#ann_manytomany) on the owning side of the relation requires to specify the @JoinTable annotation which describes the details of the database join table. If you do not specify @JoinTable on these relations reasonable mapping defaults apply using the affected table and the column names. Required attributes: * name - Database name of the join-table -* joinColumns - An array of @JoinColumn annotations describing the join-relation between the owning entites table and the join table. +* joinColumns - An array of @JoinColumn annotations describing the join-relation between the owning entities table and the join table. * inverseJoinColumns - An array of @JoinColumn annotations describing the join-relation between the inverse entities table and the join table. Optional attributes: @@ -345,7 +345,7 @@ Optional attributes: * cascade - Cascade Option * fetch - One of LAZY or EAGER -* inversedBy - The inversedBy attribute designates the field in the entity that is the inverse side of the relationship. +* inversedBy - The inversedBy attribute designates the field in the entity that is the inverse side of the relationship. Example: @@ -521,7 +521,7 @@ Marks a method on the entity to be called as a @PreUpdate event. Only works with +++ @SequenceGenerator -For the use with @generatedValue(strategy="SEQUENCE") this annotation allows to specifiy details about the sequence, +For the use with @generatedValue(strategy="SEQUENCE") this annotation allows to specify details about the sequence, such as the increment size and initial values of the sequence. Required attributes: diff --git a/manual/en/architecture.txt b/manual/en/architecture.txt index 81c33ea49..e9ef689d5 100644 --- a/manual/en/architecture.txt +++ b/manual/en/architecture.txt @@ -54,7 +54,7 @@ entity instance still holds references to proxy objects or is still managed by a If you intend to serialize (and unserialize) entity instances that still hold references to proxy objects you may run into problems with private properties because of technical limitations. Proxy objects implement `__sleep` and it is not possible for `__sleep` to return names of -private properties in parent classes. On ther other hand it is not a solution for proxy objects +private properties in parent classes. On the other hand it is not a solution for proxy objects to implement `Serializable` because Serializable does not work well with any potential cyclic object references (at least we did not find a way yet, if you did, please contact us). diff --git a/manual/en/association-mapping.txt b/manual/en/association-mapping.txt index dc30ce31b..52ba3200f 100644 --- a/manual/en/association-mapping.txt +++ b/manual/en/association-mapping.txt @@ -11,9 +11,9 @@ When mapping bidirectional associations it is important to understand the concep The following rules apply to *bidirectional* associations: -* The inverse side of a bidirectional relationship must refer to its owning side by use of the mappedBy attribute of the OneToOne, OneToMany, or ManyToMany mapping declaration. The mappedBy attribute designates the field in the entity that is the owner of the relationship. -* The owning side of a bidirectional relationship must refer to its inverse side by use of the inversedBy attribute of the OneToOne, ManyToOne, or ManyToMany mapping declaration. The inversedBy attribute designates the field in the entity that is the inverse side of the relationship. -* The many side of OneToMany/ManyToOne bidirectional relationships *must* be the owning side, hence the mappedBy element can not be specified on the ManyToOne side. +* The inverse side of a bidirectional relationship must refer to its owning side by use of the mappedBy attribute of the OneToOne, OneToMany, or ManyToMany mapping declaration. The mappedBy attribute designates the field in the entity that is the owner of the relationship. +* The owning side of a bidirectional relationship must refer to its inverse side by use of the inversedBy attribute of the OneToOne, ManyToOne, or ManyToMany mapping declaration. The inversedBy attribute designates the field in the entity that is the inverse side of the relationship. +* The many side of OneToMany/ManyToOne bidirectional relationships *must* be the owning side, hence the mappedBy element can not be specified on the ManyToOne side. * For OneToOne bidirectional relationships, the owning side corresponds to the side that contains the corresponding foreign key (@JoinColumn(s)). * For ManyToMany bidirectional relationships either side may be the owning side (the side that defines the @JoinTable and/or does not make use of the mappedBy attribute, thus using a default join table). @@ -43,7 +43,7 @@ in the database. ++ Collections -In all the examples of many-valued associations in this manual we will make use of a `Collection` interface and a corresponding default implementation `ArrayCollection` that are defined in the `Doctrine\Common\Collections` namespace. Why do we need that? Doesn't that couple my domain model to Doctrine? Unfortunately, PHP arrays, while being great for many things, do not make up for good collections of business objects, especially not in the context of an ORM. The reason is that plain PHP arrays can not be transparently extended / instrumented in PHP code, which is necessary for a lot of advanced ORM features. The classes / interfaces that come closest to an OO collection are ArrayAccess and ArrayObject but until instances of these types can be used in all places where a plain array can be used (something that may happen in PHP6) their useability is fairly limited. You "can" type-hint on `ArrayAccess` instead of `Collection`, since the Collection interface extends `ArrayAccess`, but this will severely limit you in the way you can work with the collection, because the `ArrayAccess` API is (intentionally) very primitive and more importantly because you can not pass this collection to all the useful PHP array functions, which makes it very hard to work with. +In all the examples of many-valued associations in this manual we will make use of a `Collection` interface and a corresponding default implementation `ArrayCollection` that are defined in the `Doctrine\Common\Collections` namespace. Why do we need that? Doesn't that couple my domain model to Doctrine? Unfortunately, PHP arrays, while being great for many things, do not make up for good collections of business objects, especially not in the context of an ORM. The reason is that plain PHP arrays can not be transparently extended / instrumented in PHP code, which is necessary for a lot of advanced ORM features. The classes / interfaces that come closest to an OO collection are ArrayAccess and ArrayObject but until instances of these types can be used in all places where a plain array can be used (something that may happen in PHP6) their usability is fairly limited. You "can" type-hint on `ArrayAccess` instead of `Collection`, since the Collection interface extends `ArrayAccess`, but this will severely limit you in the way you can work with the collection, because the `ArrayAccess` API is (intentionally) very primitive and more importantly because you can not pass this collection to all the useful PHP array functions, which makes it very hard to work with. > **CAUTION** > The Collection interface and ArrayCollection class, like everything else in the @@ -57,7 +57,7 @@ In all the examples of many-valued associations in this manual we will make use ++ Mapping Defaults -Before we introduce all the association mappings in detailyou should note that the @JoinColumn and @JoinTable +Before we introduce all the association mappings in detail, you should note that the @JoinColumn and @JoinTable definitions are usually optional and have sensible default values. The defaults for a join column in a one-to-one/many-to-one association is as follows: diff --git a/manual/en/basic-mapping.txt b/manual/en/basic-mapping.txt index 7a1359ccc..39120851f 100644 --- a/manual/en/basic-mapping.txt +++ b/manual/en/basic-mapping.txt @@ -237,7 +237,7 @@ This tells Doctrine to automatically generate a value for the identifier. How th +++ Identifier Generation Strategies The previous example showed how to use the default identifier generation strategy without knowing the underlying database with the AUTO-detection strategy. -It is also possible to specifiy the identifier generation strategy more explicitly, which allows to make use of some additional features. +It is also possible to specify the identifier generation strategy more explicitly, which allows to make use of some additional features. Here is the list of possible generation strategies: @@ -256,7 +256,7 @@ Here is the list of possible generation strategies: ++++ Sequence Generator The Sequence Generator can currently be used in conjunction with Oracle or Postgres and allows some additional configuration options besides -specifiying the sequence's name: +specifying the sequence's name: [php] class User { @@ -292,7 +292,7 @@ Doctrine can generate identifier values for the allocationSizes amount of entiti +++ Composite Keys -Doctrine 2 allows to use composite primary keys. There are however some restrictions oposed to using a single identifier. +Doctrine 2 allows to use composite primary keys. There are however some restrictions opposed to using a single identifier. The use of the `@GeneratedValue` annotation is only supported for simple (not composite) primary keys, which means you can only use composite keys if you generate the primary key values yourself before calling `EntityManager#persist()` on the entity. diff --git a/manual/en/best-practices.txt b/manual/en/best-practices.txt index 9c095a5ae..116761b5f 100644 --- a/manual/en/best-practices.txt +++ b/manual/en/best-practices.txt @@ -72,6 +72,6 @@ Foreign keys have no meaning whatsoever in an object model. Foreign keys are how While Doctrine will automatically wrap all DML operations in a transaction on flush(), it is considered best practice to explicitly set the transaction boundaries yourself. Otherwise every single query is wrapped in a small transaction (Yes, SELECT queries, too) since you can not talk to your database outside of a transaction. -While such short transactions for read-only (SELECT) queries generally dont have any noticable performance impact, it is still preferrable to use fewer, well-defined transactions +While such short transactions for read-only (SELECT) queries generally don't have any noticeable performance impact, it is still preferable to use fewer, well-defined transactions that are established through explicit transaction boundaries. diff --git a/manual/en/dql-doctrine-query-language.txt b/manual/en/dql-doctrine-query-language.txt index e92db7aef..c8dcefbc9 100644 --- a/manual/en/dql-doctrine-query-language.txt +++ b/manual/en/dql-doctrine-query-language.txt @@ -273,7 +273,7 @@ Get all users that have no phonenumber $query = $em->createQuery('SELECT u FROM CmsUser u WHERE u.phonenumbers IS EMPTY'); $users = $query->getResult(); -Get all instances of a specific type, for use with inheritance hierachies: +Get all instances of a specific type, for use with inheritance hierarchies: [php] $query = $em->createQuery('SELECT u FROM Doctrine\Tests\Models\Company\CompanyPerson u WHERE u INSTANCE OF Doctrine\Tests\Models\Company\CompanyEmployee'); @@ -304,7 +304,7 @@ You use the partial syntax when joining as well: The INDEX BY construct is nothing that directly translates into SQL but that affects object and array hydration. After each FROM and JOIN clause you specify by which field this class should be indexed in the result. By default a result is incremented -by numerical keys starting with 0. However with INDEX BY you can specifiy any +by numerical keys starting with 0. However with INDEX BY you can specify any other column to be the key of your result, it really only makes sense with primary or unique fields though: @@ -340,7 +340,7 @@ example shows: UPDATE MyProject\Model\User u SET u.password = 'new' WHERE u.id IN (1, 2, 3) -References to related entities are only possible in the WHERE clause and using subselects. +References to related entities are only possible in the WHERE clause and using sub-selects. > **CAUTION** > DQL UPDATE statements are ported directly into a Database UPDATE statement and therefore bypass @@ -375,11 +375,11 @@ The following functions are supported in SELECT, WHERE and HAVING clauses: * CURRENT_TIME() - Returns the current time * CURRENT_TIMESTAMP() - Returns a timestamp of the current date and time. * LENGTH(str) - Returns the length of the given string -* LOCATE(needle, haystack [, offset]) - Locate the first occurance of the substring in the string. +* LOCATE(needle, haystack [, offset]) - Locate the first occurrence of the substring in the string. * LOWER(str) - returns the string lowercased. * MOD(a, b) - Return a MOD b. * SIZE(collection) - Return the number of elements in the specified collection -* SQRT(q) - Return the squareroot of q. +* SQRT(q) - Return the square-root of q. * SUBSTRING(str, start [, length]) - Return substring of given string. * TRIM([LEADING | TRAILING | BOTH] ['trchar' FROM] str) - Trim the string by the given trim char, defaults to whitespaces. * UPPER(str) - Return the upper-case of the given string. @@ -399,12 +399,12 @@ The following aggregate functions are allowed in SELECT and GROUP BY clauses: AV DQL offers a wide-range of additional expressions that are known from SQL, here is a list of all the supported constructs: -* `ALL/ANY/SOME` - Used in a WHERE clause followed by a subselect this works like the equivalent constructs in SQL. +* `ALL/ANY/SOME` - Used in a WHERE clause followed by a sub-select this works like the equivalent constructs in SQL. * `BETWEEN a AND b` and `NOT BETWEEN a AND b` can be used to match ranges of arithmetic values. * `IN (x1, x2, ...)` and `NOT IN (x1, x2, ..)` can be used to match a set of given values. * `LIKE ..` and `NOT LIKE ..` match parts of a string or text using % as a wildcard. * `IS NULL` and `IS NOT NULL` to check for null values -* `EXISTS` and `NOT EXISTS` in combination with a subselect +* `EXISTS` and `NOT EXISTS` in combination with a sub-select +++ Adding your own functions to the DQL language @@ -586,7 +586,7 @@ An instance of the `Doctrine\ORM\Query` class represents a DQL query. You create // example1: passing a DQL string $q = $em->createQuery('select u from MyProject\Model\User u'); - // example2: usin setDql + // example2: using setDql $q = $em->createQuery(); $q->setDql('select u from MyProject\Model\User u'); @@ -612,7 +612,7 @@ The use of the methods mentioned earlier is generally preferred as it leads to m +++ Pure and Mixed Results -The nature of a result returned by a DQL SELECT query retrieved through `Query#getResult()` or `Query#getArrayResult()` can be of 2 forms: **pure** and **mixed**. In the previous simple examples, you already saw a "pure" query result, with only objects. By default, the result type is **pure** but **as soon as scalar values, such as aggregate values or other scalar values that do not belong to an entity, appear in the SELECT part of the DQL query, the result becomes mixed**. A mixed result has a different structure than a pure result in order to accomodate for the scalar values. +The nature of a result returned by a DQL SELECT query retrieved through `Query#getResult()` or `Query#getArrayResult()` can be of 2 forms: **pure** and **mixed**. In the previous simple examples, you already saw a "pure" query result, with only objects. By default, the result type is **pure** but **as soon as scalar values, such as aggregate values or other scalar values that do not belong to an entity, appear in the SELECT part of the DQL query, the result becomes mixed**. A mixed result has a different structure than a pure result in order to accommodate for the scalar values. A pure result usually looks like this: @@ -755,10 +755,10 @@ Now the hydrator is ready to be used in your queries: $query = $em->createQuery('SELECT u FROM CmsUser u'); $results = $query->getResult('CustomHydrator'); -+++ Iterating Large Resultsets ++++ Iterating Large Result Sets There are situations when a query you want to execute returns a very large result-set that needs -to be processed. All the previously described hydration modes completly load a result-set into +to be processed. All the previously described hydration modes completely load a result-set into memory which might not be feasible with large result sets. See the [Batch Processing](batch-processing) section on details how to iterate large result sets. @@ -818,10 +818,10 @@ are to be used in userland: hint can be used to handle memory consumption problems with large result-sets that contain char or binary data. Doctrine has no way of implicitly reloading this data. Partially loaded objects have to be passed to `EntityManager::refresh()` if they are to be reloaded fully from the database. -* Query::HINT_REFRESH - This query is used internally by `EntityManager::refresh()` and can be used in userland aswell. +* Query::HINT_REFRESH - This query is used internally by `EntityManager::refresh()` and can be used in userland as well. If you specify this hint and a query returns the data for an entity that is already managed by the UnitOfWork, the fields of the existing entity will be refreshed. In normal operation a result-set that loads data of an already existing -entity is discarded in favour of the already existing entity. +entity is discarded in favor of the already existing entity. * Query::HINT_CUSTOM_TREE_WALKERS - An array of additional `Doctrine\ORM\Query\TreeWalker` instances that are attached to the DQL query parsing process. @@ -845,7 +845,7 @@ of the Query Cache, however if you do there are several methods to interact with ++++ First and Max Result Items (DQL Query Only) -You can limit the number of results returned from a DQL query aswell as specify the starting offset, Doctrine +You can limit the number of results returned from a DQL query as well as specify the starting offset, Doctrine then uses a strategy of manipulating the select query to return only the requested number of results: * `Query::setMaxResults($maxResults)` @@ -854,7 +854,7 @@ then uses a strategy of manipulating the select query to return only the request > **NOTE** > If your query contains a fetch-joined collection specifying the result limit methods are not working > as you would expect. Set Max Results restricts the number of database result rows, however in the -> case of fetch-joined collections one root entity might appear in many rows, effectivly hydrating +> case of fetch-joined collections one root entity might appear in many rows, effectively hydrating > less than the specified number of results. ++ EBNF @@ -866,8 +866,8 @@ The following context-free grammar, written in an EBNF variant, describes the Do * non-terminals begin with an upper case character * terminals begin with a lower case character * parentheses (...) are used for grouping -* square brackets [...] are used for defining an optional part, eg. zero or one time -* curly brackets {...} are used for repetion, eg. zero or more times +* square brackets [...] are used for defining an optional part, e.g. zero or one time +* curly brackets {...} are used for repetition, e.g. zero or more times * double quotation marks "..." define a terminal string a vertical bar | represents an alternative +++ Terminals @@ -901,7 +901,7 @@ The following context-free grammar, written in an EBNF variant, describes the Do AbstractSchemaName ::= identifier /* identifier that must be a field (the "name" of "u.name") */ - /* This is responsable to know if the field exists in Object, no matter if it's a relation or a simple field */ + /* This is responsible to know if the field exists in Object, no matter if it's a relation or a simple field */ FieldIdentificationVariable ::= identifier /* identifier that must be a collection-valued association field (to-many) (the "Phonenumbers" of "u.Phonenumbers") */ diff --git a/manual/en/events.txt b/manual/en/events.txt index 3df59c619..3218814d3 100644 --- a/manual/en/events.txt +++ b/manual/en/events.txt @@ -111,7 +111,7 @@ The EntityManager and UnitOfWork trigger a bunch of events during the life-time * postUpdate - The postUpdate event occurs after the database update operations to entity data. * postLoad - The postLoad event occurs for an entity after the entity has been loaded into the current EntityManager from the database or after the refresh operation has been applied to it. * loadClassMetadata - The loadClassMetadata event occurs after the mapping metadata for a class has been loaded from a mapping source (annotations/xml/yaml). -* onFlush - The onFlush event occours after the change-sets of all managed entities are computed. This event is not a lifecycle callback. +* onFlush - The onFlush event occurs after the change-sets of all managed entities are computed. This event is not a lifecycle callback. > **CAUTION** > Note that the postLoad event occurs for an entity before any associations have been @@ -126,8 +126,8 @@ You can access the Event constants from the `Events` class in the ORM package. These can be hooked into by two different types of event listeners: -* Lifecycle Callbacks are methods on the entity classes that are called when the event is triggered. They recieve absolutely no arguments and are specifically designed to allow changes inside the entity classes state. -* Lifecycle Event Listeners are classes with specific callback methods that recieves some kind of `EventArgs` instance which give access to the entity, EntityManager or other relevant data. +* Lifecycle Callbacks are methods on the entity classes that are called when the event is triggered. They receive absolutely no arguments and are specifically designed to allow changes inside the entity classes state. +* Lifecycle Event Listeners are classes with specific callback methods that receives some kind of `EventArgs` instance which give access to the entity, EntityManager or other relevant data. > **NOTE** > All Lifecycle events that happen during the `flush()` of an EntityManager have very specific constraints on the allowed @@ -249,7 +249,7 @@ the event type. The allowed event types are the ones listed in the previous Life ++ Listening to Lifecycle Events Lifecycle event listeners are much more powerful than the simple lifecycle callbacks that are defined on the entity -classes. They allow to implement re-usable behaviours between different entity classes, yet require much more detailed +classes. They allow to implement re-usable behaviors between different entity classes, yet require much more detailed knowledge about the inner workings of the EntityManager and UnitOfWork. Please read the *Implementing Event Listeners* section carefully if you are trying to write your own listener. @@ -420,7 +420,7 @@ to call: private function validateCreditCard($no) { - // throw an exception to interupt flush event. Transaction will be rolled back. + // throw an exception to interrupt flush event. Transaction will be rolled back. } } diff --git a/manual/en/improving-performance.txt b/manual/en/improving-performance.txt index 644636fc9..f0f05710e 100644 --- a/manual/en/improving-performance.txt +++ b/manual/en/improving-performance.txt @@ -4,14 +4,14 @@ It is highly recommended to make use of a bytecode cache like APC. A bytecode cache removes the need for parsing PHP code on every request and can greatly improve performance. > **NOTE** -> "If you care about performance and don’t use a bytecode cache then you don’t really care +> "If you care about performance and don't use a bytecode cache then you don't really care > about performance. Please get one and start using it." (Stas Malyshev, Core Contributor > to PHP and Zend Employee). ++ Metadata and Query caches -As already mentioned earlier in the chapter about configuring Doctrine, it is strongly discouraged to use Doctrine without a Metadata and Query cache (preferrably with APC or Memcache as the cache driver). Operating Doctrine without these caches means Doctrine will need to load your mapping information on every single request and has to parse each DQL query on every single request. This is a waste of resources. +As already mentioned earlier in the chapter about configuring Doctrine, it is strongly discouraged to use Doctrine without a Metadata and Query cache (preferably with APC or Memcache as the cache driver). Operating Doctrine without these caches means Doctrine will need to load your mapping information on every single request and has to parse each DQL query on every single request. This is a waste of resources. ++ Alternative Query Result Formats diff --git a/manual/en/inheritance-mapping.txt b/manual/en/inheritance-mapping.txt index 255cd435b..b7639c3c9 100644 --- a/manual/en/inheritance-mapping.txt +++ b/manual/en/inheritance-mapping.txt @@ -9,7 +9,7 @@ mapped inheritance hierarchy (through Single Table Inheritance or Class Table In > **NOTE** > -> A mapped superclass cannot be an entity, it is not queryable and persistent relationships defined by a mapped +> A mapped superclass cannot be an entity, it is not query-able and persistent relationships defined by a mapped > superclass must be unidirectional. For further support of inheritance, the single or joined table inheritance > features have to be used. diff --git a/manual/en/limitations-and-known-issues.txt b/manual/en/limitations-and-known-issues.txt index 23540c10e..9439ae1b2 100644 --- a/manual/en/limitations-and-known-issues.txt +++ b/manual/en/limitations-and-known-issues.txt @@ -138,7 +138,7 @@ as this is a pretty important feature we plan to add support for it in the futur +++ Custom Persisters -A Perister in Doctrine is an object that is responsible for the hydration and write operations of an entity against the database. +A Persister in Doctrine is an object that is responsible for the hydration and write operations of an entity against the database. Currently there is no way to overwrite the persister implementation for a given entity, however there are several use-cases that can benefit from custom persister implementations: diff --git a/manual/en/metadata-drivers.txt b/manual/en/metadata-drivers.txt index b07310346..9ba308cf5 100644 --- a/manual/en/metadata-drivers.txt +++ b/manual/en/metadata-drivers.txt @@ -14,7 +14,7 @@ Doctrine provides a few different ways for you to specify your metadata: Something important to note about the above drivers is they are all an intermediate step to the same end result. The mapping information is populated to `Doctrine\ORM\Mapping\ClassMetadata` instances. So in the end, Doctrine -only ever has to work with the api of the `ClassMetadata` class to get mapping +only ever has to work with the API of the `ClassMetadata` class to get mapping information for an entity. > **TIP** diff --git a/manual/en/native-sql.txt b/manual/en/native-sql.txt index f6dd12096..39de3ec68 100644 --- a/manual/en/native-sql.txt +++ b/manual/en/native-sql.txt @@ -18,7 +18,7 @@ A Doctrine result can contain the following components: * Entity results. These represent root result elements. * Joined entity results. These represent joined entities in associations of root entity results. * Field results. These represent a column in the result set that maps to a field of an entity. A field result always belongs to an entity result or joined entity result. - * Scalar results. These represent scalar values in the result set that will appear in each result row. Adding scalar results to a ResultSetMapping can also cause the overall result to becomed **mixed** (see DQL - Doctrine Query Language) if the same ResultSetMapping also contains entity results. + * Scalar results. These represent scalar values in the result set that will appear in each result row. Adding scalar results to a ResultSetMapping can also cause the overall result to become **mixed** (see DQL - Doctrine Query Language) if the same ResultSetMapping also contains entity results. * Meta results. These represent columns that contain meta-information, such as foreign keys and discriminator columns. When querying for objects (`getResult()`), all meta columns of root entities or joined entities must be present in the SQL query and mapped accordingly using `ResultSetMapping#addMetaResult`. diff --git a/manual/en/partial-objects.txt b/manual/en/partial-objects.txt index bb8f914b8..68e23dce9 100644 --- a/manual/en/partial-objects.txt +++ b/manual/en/partial-objects.txt @@ -21,7 +21,7 @@ right? These blind assumptions can quickly lead to null reference errors when working with such partial objects. It gets worse with the scenario of an optional association (0..1 to 1). When -the associated field is NULL, you dont know whether this object does not have +the associated field is NULL, you don't know whether this object does not have an associated object or whether it was simply not loaded when the owning object was loaded from the database. diff --git a/manual/en/query-builder.txt b/manual/en/query-builder.txt index b07bf6d79..0ad69b3e3 100644 --- a/manual/en/query-builder.txt +++ b/manual/en/query-builder.txt @@ -3,7 +3,7 @@ A `QueryBuilder` provides an API that is designed for conditionally constructing a DQL query in several steps. -It provides a set of classes and methods that is able to programatically build you queries, and also provides a fluent API. +It provides a set of classes and methods that is able to programmatically build queries, and also provides a fluent API. This means that you can change between one methodology to the other as you want, and also pick one if you prefer. +++ Constructing a new QueryBuilder object @@ -17,7 +17,7 @@ Here is an example how to build a `QueryBuilder` object: // example1: creating a QueryBuilder instance $qb = $em->createQueryBuilder(); -Once you created an instance of QueryBuilder, it provides a set of useful informative functions that you can use. +Once you have created an instance of QueryBuilder, it provides a set of useful informative functions that you can use. One good example is to inspect what type of object the `QueryBuilder` is. [php] @@ -46,16 +46,16 @@ It is possible to retrieve the associated `EntityManager` of the current `QueryB // example5: retrieve the associated Query object with the processed DQL $q = $qb->getQuery(); -Internally, `QueryBuilder` works with a DQL cache, which prevents multiple processment if called multiple times. Any changes that may affect the generated DQL actually modifies the state of `QueryBuilder` to a stage we call as STATE_DIRTY. -One `QueryBuilder`can be in two different state: +Internally, `QueryBuilder` works with a DQL cache to increase performance. Any changes that may affect the generated DQL actually modifies the state of `QueryBuilder` to a stage we call STATE_DIRTY. +One `QueryBuilder` can be in two different states: * `QueryBuilder::STATE_CLEAN`, which means DQL haven't been altered since last retrieval or nothing were added since its instantiation * `QueryBuilder::STATE_DIRTY`, means DQL query must (and will) be processed on next retrieval +++ Working with QueryBuilder -All helper methods in `QueryBuilder` relies actually on a single one: `add()`. -This method is the responsable to build every piece of DQL. It takes 3 parameters: `$dqlPartName`, `$dqlPart` and `$append` (default=false) +All helper methods in `QueryBuilder` actually rely on a single one: `add()`. +This method is responsible of building every piece of DQL. It takes 3 parameters: `$dqlPartName`, `$dqlPart` and `$append` (default=false) * `$dqlPartName`: Where the `$dqlPart` should be placed. Possible values: select, from, where, groupBy, having, orderBy * `$dqlPart`: What should be placed in `$dqlPartName`. Accepts a string or any instance of `Doctrine\ORM\Query\Expr\*` @@ -110,7 +110,7 @@ If you've got several parameters to bind to your query, you can also use setPara $qb->setParameters(array(1 => 'value for ?1', 2 => 'value for ?2')); -Getting already bound parameters is easy - simply use the abovementioned syntax with "getParameter()" or "getParameters()": +Getting already bound parameters is easy - simply use the above mentioned syntax with "getParameter()" or "getParameters()": [php] // $qb instanceof QueryBuilder @@ -155,7 +155,7 @@ This class is called `Expr`, which provides a set of useful static methods to he )) ->add('orderBy', $qb->expr()->orderBy('u.surname', 'ASC')); -Although it still sounds complex, the ability to programatically create conditions are the main feature of `Expr`. +Although it still sounds complex, the ability to programmatically create conditions are the main feature of `Expr`. Here it is a complete list of supported helper methods available: [php] @@ -305,9 +305,9 @@ Here it is a complete list of supported helper methods available: ++++ Helper methods -Until now it was described the hardcore level of creating queries. It may be useful to work that way for optimization purposes, but most of the time it is preferred to work higher level. -To simplify even more the way you build a query in Doctrine, we can take advantage of what we call as helper methods. For all base code, it has a set of useful methods to simplify programmer's life. -Illustrating how to work with it, here is the same example 6 written now using `QueryBuilder` helper methods: +Until now we have described the lowest level (thought of as the hardcore method) of creating queries. It may be useful to work at this level for optimization purposes, but most of the time it is preferred to work at a higher level of abstraction. +To simplify even more the way you build a query in Doctrine, we can take advantage of what we call Helper methods. For all base code, there is a set of useful methods to simplify a programmer's life. +To illustrate how to work with them, here is the same example 6 re-written using `QueryBuilder` helper methods: [php] // $qb instanceof QueryBuilder @@ -333,7 +333,7 @@ Here is a converted example 8 to suggested standard way to build queries: )) ->orderBy('u.surname', 'ASC')); -Here is a complete list of helper methods in `QueryBuilder`: +Here is a complete list of helper methods available in `QueryBuilder`: [php] class QueryBuilder @@ -378,7 +378,7 @@ Here is a complete list of helper methods in `QueryBuilder`: // Example - $qb->orWhere($qb->expr()->between('u.id', 1, 10)); public function orWhere($where); - // NOTE: -> groupBy() overrides all previously set grouping items + // NOTE: -> groupBy() overrides all previously set grouping conditions // // Example - $qb->groupBy('u.id') public function groupBy($groupBy); @@ -398,7 +398,7 @@ Here is a complete list of helper methods in `QueryBuilder`: // Example - $qb->orHaving($qb->expr()->lte('g.managerLevel', '100')) public function orHaving($having); - // NOTE: -> orderBy() overrides all previously set ordering items + // NOTE: -> orderBy() overrides all previously set ordering conditions // // Example - $qb->orderBy('u.surname', 'DESC') public function orderBy($sort, $order = null); diff --git a/manual/en/tools.txt b/manual/en/tools.txt index 152788c7a..d461bafcf 100644 --- a/manual/en/tools.txt +++ b/manual/en/tools.txt @@ -38,7 +38,7 @@ When dealing with the ORM package, the EntityManagerHelper is required: )); $cli->setHelperSet($helperSet); -The HelperSet instance has to be generated in a separate file (ie. `cli-config.php`) that contains typical Doctrine +The HelperSet instance has to be generated in a separate file (i.e. `cli-config.php`) that contains typical Doctrine bootstrap code and predefines the needed HelperSet attributes mentioned above. A typical `cli-config.php` file looks as follows: [php] @@ -140,7 +140,7 @@ To drop the schema you can use the `dropSchema()` method. $tool->dropSchema($classes); This drops all the tables that are currently used by your metadata model. -When you are changing your metadata alot during development you might want +When you are changing your metadata a lot during development you might want to drop the complete database instead of only the tables of the current model to clean up with orphaned tables. @@ -185,7 +185,7 @@ Before using the orm:schema-tool commands, remember to configure your cli-config > > When using the Annotation Mapping Driver you have to either setup your autoloader in the cli-config.php > correctly to find all the entities, or you can use the second argument of the `EntityManagerHelper` to -> specifiy all the paths of your entities (or mapping files), i.e. +> specify all the paths of your entities (or mapping files), i.e. > `new \Doctrine\ORM\Tools\Console\Helper\EntityManagerHelper($em, $mappingPaths);` ++ Convert Mapping Information diff --git a/manual/en/transactions-and-concurrency.txt b/manual/en/transactions-and-concurrency.txt index 9e85a9cba..7d49539ed 100644 --- a/manual/en/transactions-and-concurrency.txt +++ b/manual/en/transactions-and-concurrency.txt @@ -10,7 +10,7 @@ For the most part, Doctrine 2 already takes care of proper transaction demarcati operations (INSERT/UPDATE/DELETE) are queued until `EntityManager#flush()` is invoked which wraps all of these changes in a single transaction. -However, Doctrine 2 also allows (and ecourages) you to take over and control transaction demarcation yourself. +However, Doctrine 2 also allows (and encourages) you to take over and control transaction demarcation yourself. These are two ways to deal with transactions when using the Doctrine ORM and are now described in more detail. @@ -85,10 +85,10 @@ is automatically rolled back and the `EntityManager` closed. When using explicit transaction demarcation and an exception occurs, the transaction should be rolled back immediately and the `EntityManager` closed by invoking `EntityManager#close()` and subsequently discarded, as demonstrated in the example above. This can be handled elegantly by the control abstractions shown earlier. -Note that when catching `Exception` you should generally rethrow the exception. If you intend to +Note that when catching `Exception` you should generally re-throw the exception. If you intend to recover from some exceptions, catch them explicitly in earlier catch blocks (but do not forget to rollback the transaction and close the `EntityManager` there as well). All other best practices of exception handling apply -similarly (i.e. either log or rethrow, not both, etc.). +similarly (i.e. either log or re-throw, not both, etc.). As a result of this procedure, all previously managed or removed instances of the `EntityManager` become detached. The state of the detached objects will be the state at the point at which the transaction was rolled back. @@ -96,7 +96,7 @@ The state of the objects is in no way rolled back and thus the objects are now o The application can continue to use the detached objects, knowing that their state is potentially no longer accurate. -If you intend to start another unit of work after an exception has occured you should do that with a new `EntityManager`. +If you intend to start another unit of work after an exception has occurred you should do that with a new `EntityManager`. ++ Locking Support @@ -115,7 +115,7 @@ Doctrine has integrated support for automatic optimistic locking via a version f that should be protected against concurrent modifications during long-running business transactions gets a version field that is either a simple number (mapping type: integer) or a timestamp (mapping type: datetime). When changes to such an entity are persisted at the end of a long-running conversation the version of the entity is compared to -the version in the database and if they dont match, an `OptimisticLockException` is thrown, indicating that the +the version in the database and if they don't match, an `OptimisticLockException` is thrown, indicating that the entity has been modified by someone else already. You designate a version field in an entity as follows. In this example we'll use an integer. @@ -229,12 +229,12 @@ And the change headline action (POST Request): +++ Pessimistic Locking Doctrine 2 supports Pessimistic Locking at the database level. No attempt is being made to implement pessimistic locking -inside Doctrine, rather vendor-specific and ANSI-SQL commands are used to aquire row-level locks. Every Entity can +inside Doctrine, rather vendor-specific and ANSI-SQL commands are used to acquire row-level locks. Every Entity can be part of a pessimistic lock, there is no special metadata required to use this feature. However for Pessimistic Locking to work you have to disable the Auto-Commit Mode of your Database and start a transaction around your pessimistic lock use-case using the "Approach 2: Explicit Transaction Demarcation" described -above. Doctrine 2 will throw an Exception if you attempt to aquire an pessimistic lock and no transaction is running. +above. Doctrine 2 will throw an Exception if you attempt to acquire an pessimistic lock and no transaction is running. Doctrine 2 currently supports two pessimistic lock modes: diff --git a/manual/en/working-with-associations.txt b/manual/en/working-with-associations.txt index 06dd1f767..fe4786df2 100644 --- a/manual/en/working-with-associations.txt +++ b/manual/en/working-with-associations.txt @@ -325,7 +325,7 @@ Using the User-Comment entities from above, a very simple example can show the p // not calling $favoriteComment->getUserFavorites()->add($user); $user->getFavorites()->contains($favoriteComment); // TRUE - $favoriteComment->getUerFavorites()->contains($user); // FALSE + $favoriteComment->getUserFavorites()->contains($user); // FALSE There are to approaches to handle this problem in your code: diff --git a/manual/en/working-with-objects.txt b/manual/en/working-with-objects.txt index 5fa6455c5..0decce091 100644 --- a/manual/en/working-with-objects.txt +++ b/manual/en/working-with-objects.txt @@ -1,7 +1,7 @@ In this chapter we will help you understand the `EntityManager` and the `UnitOfWork`. A Unit of Work is similar to an object-level transaction. A new Unit of Work is -implicity started when an EntityManager is initially created or after +implicitly started when an EntityManager is initially created or after `EntityManager#flush()` has been invoked. A Unit of Work is committed (and a new one started) by invoking `EntityManager#flush()`. @@ -213,7 +213,7 @@ The semantics of the remove operation, applied to an entity X are as follows: After an entity has been removed its in-memory state is the same as before the removal, except for generated identifiers. -Removing an entity will also automatically delete any exisiting records in many-to-many +Removing an entity will also automatically delete any existing records in many-to-many join tables that link this entity. The action taken depends on the value of the `@joinColumn` mapping attribute "onDelete". Either Doctrine issues a dedicated `DELETE` statement for records of each join table or it depends on the foreign key semantics of @@ -234,7 +234,7 @@ ways with very different performance impacts. 3. Using foreign key semantics `onDelete="CASCADE"` can force the database to remove all associated objects internally. This strategy is a bit tricky to get right but can be very powerful and fast. You should be aware - however that using strategy 1 (`CASCADE=REMOVE`) completly by-passes + however that using strategy 1 (`CASCADE=REMOVE`) completely by-passes any foreign key `onDelete=CASCADE` option, because Doctrine will fetch and remove all associated entities explicitly nevertheless. @@ -300,7 +300,7 @@ MERGE or ALL, Y is merged recursively as Y'. For all such Y referenced by X, X' The `merge` operation will throw an `OptimisticLockException` if the entity being merged uses optimistic locking through a version field and the versions -of the entity being merged and the managed copy dont match. This usually means +of the entity being merged and the managed copy don't match. This usually means that the entity has been modified while being detached. The `merge` operation is usually not as frequently needed and used as `persist` @@ -448,7 +448,7 @@ Essentially, `EntityManager#find()` is just a shortcut for the following: // $em instanceof EntityManager $user = $em->getRepository('MyProject\Domain\User')->find($id); -`EntityManager#getRepository($entityName)` returns a repository object which provides many ways to retreive entities of the specified type. By default, the repository instance is of type `Doctrine\ORM\EntityRepository`. You can also use custom repository classes as shown later. +`EntityManager#getRepository($entityName)` returns a repository object which provides many ways to retrieve entities of the specified type. By default, the repository instance is of type `Doctrine\ORM\EntityRepository`. You can also use custom repository classes as shown later. +++ By Simple Conditions @@ -489,7 +489,7 @@ Whenever you have a managed entity instance at hand, you can traverse and use an +++ By DQL The most powerful and flexible method to query for persistent objects is the Doctrine Query Language, an object query language. DQL enables you to query for persistent objects in the language of objects. DQL understands classes, fields, inheritance and associations. -DQL is syntactically very similar to the familar SQL but *it is not SQL*. +DQL is syntactically very similar to the familiar SQL but *it is not SQL*. A DQL query is represented by an instance of the `Doctrine\ORM\Query` class. You create a query using `EntityManager#createQuery($dql)`. Here is a simple example: diff --git a/manual/en/xml-mapping.txt b/manual/en/xml-mapping.txt index b96420147..0ebdd863f 100644 --- a/manual/en/xml-mapping.txt +++ b/manual/en/xml-mapping.txt @@ -230,7 +230,7 @@ Optional attributes for ``: > **NOTE** > > If you want to implement a cross-vendor compatible application you have to specify and -> additionaly define the element, if Doctrine chooses the sequence strategy for a platform. +> additionally define the element, if Doctrine chooses the sequence strategy for a platform. +++ Defining a Mapped Superclass @@ -256,7 +256,7 @@ a mapped superclass. +++ Defining Inheritance Mappings There are currently two inheritance persistence strategies that you can choose from when defining entities that -inherit from each other. Single Table inheritance saves the fields of the complete inheritance hierachy in a single table, +inherit from each other. Single Table inheritance saves the fields of the complete inheritance hierarchy in a single table, joined table inheritance creates a table for each entity combining the fields using join conditions. You can specify the inheritance type in the `` element and then use the `` and @@ -276,7 +276,7 @@ The allowed values for inheritance-type attribute are `JOINED` or `SINGLE_TABLE` > **NOTE** > -> All inheritance related definitions have to be defined on the root entity of the hierachy. +> All inheritance related definitions have to be defined on the root entity of the hierarchy. +++ Defining Lifecycle Callbacks @@ -292,7 +292,7 @@ You can define the lifecycle callback methods on your entities using the `` element. The required +You can define One-To-One Relations/Associations using the `` element. The required and optional attributes depend on the associations being on the inverse or owning side. For the inverse side the mapping is as simple as: @@ -304,7 +304,7 @@ For the inverse side the mapping is as simple as: Required attributes for inverse One-To-One: -* field - Name of the property/field on the entitys PHP class. +* field - Name of the property/field on the entity's PHP class. * target-entity - Name of the entity associated entity class. If this is not qualified the namespace of the current class is prepended. * mapped-by - Name of the field on the owning side (here Address entity) that contains the owning side association. @@ -317,7 +317,7 @@ For the owning side this mapping would look like: Required attributes for owning One-to-One: -* field - Name of the property/field on the entitys PHP class. +* field - Name of the property/field on the entity's PHP class. * target-entity - Name of the entity associated entity class. If this is not qualified the namespace of the current class is prepended. Optional attributes for owning One-to-One: @@ -331,7 +331,7 @@ Without the nested `` element Doctrine assumes to foreign key to Entities table. This is because the `MyProject\Address` entity is the owning side of this association, which means it contains the foreign key. -The completed explictly defined mapping is: +The completed explicitly defined mapping is: [xml] @@ -352,7 +352,7 @@ compared to the one-to-one case. The minimal mapping for this association looks Required attributes: -* field - Name of the property/field on the entitys PHP class. +* field - Name of the property/field on the entity's PHP class. * target-entity - Name of the entity associated entity class. If this is not qualified the namespace of the current class is prepended. Optional attributes: @@ -362,7 +362,7 @@ Optional attributes: * fetch - Either LAZY or FETCH, defaults to LAZY. This definition relies on a bunch of mapping defaults with regards to the naming of the join-column/foreign key. The -explictly defined mapping includes a `` tag nested inside the many-to-one association tag: +explicitly defined mapping includes a `` tag nested inside the many-to-one association tag: [xml] @@ -387,7 +387,7 @@ uni-directional one-to-many association, which means this association only ever Required attributes: -* field - Name of the property/field on the entitys PHP class. +* field - Name of the property/field on the entity's PHP class. * target-entity - Name of the entity associated entity class. If this is not qualified the namespace of the current class is prepended. * mapped-by - Name of the field on the owning side (here Phonenumber entity) that contains the owning side association. @@ -407,7 +407,7 @@ you can omit many definitions and rely on their implicit values. Required attributes: -* field - Name of the property/field on the entitys PHP class. +* field - Name of the property/field on the entity's PHP class. * target-entity - Name of the entity associated entity class. If this is not qualified the namespace of the current class is prepended. Optional attributes: @@ -439,7 +439,7 @@ the table name of the many-to-many join-table. +++ Cascade Element -Doctrine allows cascading of several UnitOfWork operations to related entities. You can specifiy the cascade +Doctrine allows cascading of several UnitOfWork operations to related entities. You can specify the cascade operations in the `` element inside any of the association mapping tags. [xml] @@ -451,7 +451,7 @@ operations in the `` element inside any of the association mapping ta -Besides `` the following operations can be specifed by their respective tags: +Besides `` the following operations can be specified by their respective tags: * `` * ``