doctrine / orm-documentation

OUTDATED REPOSITORY - PLEASE MAKE PULL REQUESTS TO DOCTRINE2 REPOSITORY

Moved

The documentation has moved into the Doctrine2 ORM project: https://github.com/doctrine/doctrine2

orm-documentation's Issues

Working with asocitions typo?

I tried to pull request the modified rst file but in rst didn't come up the example.. too new.
here is the problem:
in http://www.doctrine-project.org/docs/orm/2.0/en/reference/working-with-associations.html example:
Class User:
/**
* Bidirectional - One-To-Many (INVERSE SIDE)
*
* @OneToMany(targetEntity="Comment", mappedBy="author")
*/
private $commentsAuthored;
....

Class comment:

/**
* Bidirectional - Many Comments are authored by one user (OWNING SIDE)
*
* @manytoone(targetEntity="User", inversedBy="authoredComments")
*/
private $author;
....

AutohredComments vs CommentsAuthored?¿?¿?¿

Thanks.

Fatal Errors in Online Tutorial's Code Samples

Hi,

I was reading Getting Started guide, and following its examples.
There are some issues.

First off, listings of Bug.php in the "A first prototype" section. When I
saw the 2nd listing of Bug.php, i though that it is entirely different
from the 1st listing of the same file. You should include "..." characters
to tell the reader that some lines are "ADDED" into the 2nd listing,
instead of a new version.

Just below the title " "A first prototype", there is a black box which
contains code for Bug.php and Product.php. These two files need
two separate boxes.

Bug.php's listing, lacks the following methods:
setCreated() , setStatus(), setDescription(), and getId()

The following sentence used in Getting Started guide, is not very clear:
Since we haven’t namespaced our three entities, we have to implement three mapping files called Bug.dcm.xml, Product.dcm.xml and User.dcm.xml (or .yml) and put them into a distinct folder for mapping configurations.

It should be changed it:
To namespace our three entities, we may choose one of the following methods:

1. XML-based mapping file (Bug.dcm.xml, Product.dcm.xml and User.dcm.xml)
2. YAML-based files
3. Inline annotations within PHP source code
   You can choose any of these methods.

The docmentation may also include a solution for people that are not using PEAR.
Just place the Doctrine directory into your include_path.
Open bin/doctrine.php and add somethnig like:

set_include_path(
realpath(dirname(FILE) . '/../')
);

Wrong comments in DQL examples

In http://www.doctrine-project.org/docs/orm/2.0/en/reference/dql-doctrine-query-language.html, under "With COUNT DISTINCT:" and "With Arithmetic Expression in WHERE clause:", the comment after $query->getResult() says "array of ForumUser objects", which is probably wrong. It seems like it was copied from the previous examples and wasn't changed.

Wrong namespace

I found one error at 26.2.2. Configuration (Non-PEAR). At line number 7 appears

use Doctrine\DBAL\Tools\Console\Helper\EntityManagerHelper;

and it would be

use Doctrine_ORM\Tools\Console\Helper\EntityManagerHelper;_

building documentation

in order to be able to successfully run bin/generate-docs.sh i had to install texlive-latex-extra on my ubuntu machine. otherwise i get

build/pdf/sphinx.sty: File `fancybox.sty' not found.
build/pdf/sphinx.sty:14: Emergency stop.
build/pdf/sphinx.sty:14: leading text: \RequirePackage

and another package i had to install is texlive-fonts-recommended - not sure if this is ubuntu specific or if it can go into bin/install-dependencies.sh. even if its specific, might be worth to mention it in the readme

"One-To-Many Unidirectional" missing example

http://docs.doctrine-project.org/en/2.0.x/reference/association-mapping.html#one-to-many-unidirectional-with-join-table
There is no example for "One-To-Many Unidirectional with Join Table": only the generated MySQL schema is shown

delete the doc for a number of cache provider methods that don't exist

http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/caching.html#deleting

http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/caching.html#counting

I checked source code. Most of the methods don't exist. They are better to be removed from the doc. I tried to use those functions and was surprised that didn't exist.

I'll send a PR soon.

Need for mapping annotations to ORM in Models

AS documented here http://symfony.com/doc/current/book/doctrine.html there is a need to alias the annotations with ORM which prevents issues when integrating with unit testing.

Can this be sold as a best practice and documentation updated to reflect that

SELECT NEW Contradiction in documentation

It seems that documantation is contradictory. In dql-doctrine-query-language.rst i see example of SELECT NEW but in grammar I don't see it beeing implemented. Also in my symfony (with doctrine 2.3.3) I get lexer error on that example.

Confusing code examples

In code examples for (eg. for ArrayCollection) should be whole codes, because this is pretty confusing. I am new to Doctrine2, so I may get it wrong (because it is confusing ;) ), but as I understand, there should be whole code from previous examples, but actual look of tutorial makes me think to delete previous code and replace it with ONLY the new code...

Did I make myself clear or was I confusing? :)

Link in 14.7.5 doesn't work

The link in 14.7.5 to Batch Processing doesn't work

Update ApiGen to 2.8 for the API reference

ApiGen 2.6 has an annoying behaviour where moving the mouse over a class’ method summary expands the rows to display method details, disrupting reading. This problem is now fixed in ApiGen 2.8 and details are displayed on click. Could you please update to that version?

The corrected behaviour can be tested here.

Borken links in Getting Started guide

The link to "DBAL Configuration section of the manual" is broken.
http://www.doctrine-project.org/docs/orm/2.0/en/reference/dbal.html

Bug in QueryBuilder::add() method, param $append has no effect for where/having DQL parts

Bug in QueryBuilder::add() method

Now $append param of QueryBuilder::add() method has no effect for where and having parts.

In example:

$query->add('where', 'u.some = ?1');
$query->add('where', 'u.other = ?2', true);

will result in the loss of condition u.some = ?1

Explanation in code

526 line of Doctrine/ORM/QueryBuilder.php, part of body add() method:

if ($append && $isMultiple) {
    if (is_array($dqlPart)) {
        $key = key($dqlPart);
        $this->_dqlParts[$dqlPartName][$key][] = $dqlPart[$key];
    } else {
        $this->_dqlParts[$dqlPartName][] = $dqlPart;
    }
} else {
    $this->_dqlParts[$dqlPartName] = ($isMultiple) ? array($dqlPart) : $dqlPart;
}

According to the code above $append parameter is checked in conjunction with $isMultiple variable, which is:

$isMultiple = is_array($this->_dqlParts[$dqlPartName]);

But in 56 line of this class in property _dqlParts keys where and having are equal null:

private $_dqlParts = array(
    'distinct' => false,
    'select'  => array(),
    'from'    => array(),
    'join'    => array(),
    'set'     => array(),
    'where'   => null,
    'groupBy' => array(),
    'having'  => null,
    'orderBy' => array()
);

As a result, for the parts where and having condition $append && $isMultiple will never be true, regardless of $append value.

I can offer a patch to fix this bug, if necessary.

HIDDEN and IDENTITY are undocumented

DQL function IDENTITY (for selecting the FK value of a related entity) and HIDDEN (keyword for selecting values without including in the resultset) are both undocumented.

Mapping Association Documentation vs Normal Database Terminology

I am a new Doctrine 2 user, but I have found the association mapping documentation (https://github.com/doctrine/orm-documentation/blob/master/en/reference/association-mapping.rst) to be very confusing when compared to relationationla database terminology:

a) One-to-One Unidirectional and Bidirectional mappings are actually a one-to-many however, in the uni-directional version the parent does not have a mapping to the child while in the bi-directional one the parent does

b) One-to-Many is actually a many-to-many mapping which left me all fuzzled up.

c) Many-to-Many - I have not yet got that far

Since I am sure most developers have a database background, the concepts make it difficult to match the association mapping meanings to what the database ones are like.

ManyToOne has no inversedBy param

http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/annotations-reference.html#annref-manytoone

ManyToOne has no inversedBy param.

Small typo - wrong date format

9.3. Lifecycle Callbacks

    public function doStuffOnPrePersist()
    {
        $this->createdAt = date('Y-m-d H:m:s');
    }

https://github.com/doctrine/orm-documentation/blame/master/en/reference/events.rst#L243

H:m:s should be H:i:s

CodeIgniter LIbrary Wrapper

Hello!

I've created a CodeIgniter Wrapper Library for Doctrine. I believe it works well and is well documented. The library is based on the example found here (http://docs.doctrine-project.org/en/2.0.x/cookbook/integrating-with-codeigniter.html), but is packaged in a nice, easy to install, 3rd-party library.

The library can be found here:
https://github.com/camna/codeigniter-doctrine

Could we replace this page:
http://docs.doctrine-project.org/en/2.0.x/cookbook/integrating-with-codeigniter.html

With a reference to the library?

Thanks!

in-ten-quick-steps.rst typo in code sample at step 4.

/en/tutorials/in-ten-quick-steps.rst has a typo at step №4:

public function __construct(User $author)
{
    $this->author = $author;
    $this->posts = new ArrayCollection();
}

Change "$this->posts" to "$this->comments".

Identity though foreign entities (@id on associations) - conflicting statements in documentation

http://www.doctrine-project.org/docs/orm/2.0/en/tutorials/composite-primary-keys.html#identity-through-foreign-entities.

Under this section it states that

'Set a key associationKey: with the field name of the association in YAML.'

And in the code example (for Yaml) it shows

      associationKey: true

The first statement makes it look as if you can choose a field from your associated entity to use as the primary key for the entity you are mapping - while the second example looks as if you are forced to use the primary Id of the associated entity.

I'm not sure which is correct but they cannot both be.

-Thanks

Suggestion: Change the 2.0 to "current" in the docs URL

Hey guys-

This is just a general suggestion about the website - I'm note sure if there's a better place to put this. In Symfony - following PHPUnit's lead - we removed the documentation's version from the URL and replaced it with "current". For Doctrine (taking the ORM as an example), this would mean that:

http://www.doctrine-project.org/docs/orm/2.0/en/

becomes

http://www.doctrine-project.org/docs/orm/current/en/

We made this change in Symfony-land in response to users complaining - from symfony1 - that googling always returned out-of-date documentation. This makes sense if you have the version in the URL, as all of your backlinks will link to a specific version (e.g. "2.0"), keeping the rank on that version high even as it becomes out-of-date.

Just a suggestion! Should be as easy as a symlink, but do with it what you will.

Cheers!

Clarification for STI/CTI performance warning with associations

In sections 7.2.2 and 7.3.2 of the Reference doc, there is a statement about Performance Impact which could be stated more clearly.

Replace:

"If you use a STI entity as a many-to-one or one-to-one entity you should never use one of the classes at the upper levels of the inheritance hierachy as “targetEntity”, only those that have no subclasses"

With:

"If the target-entity of a many-to-one or one-to-one association is an STI/CTI entity, it must be a leaf entity in the inheritance heirarchy, (ie. have no subclasses)."

DQL "INDEX BY" example looks buggy

In dql-doctrine-query-language.rst, when comparing examples from sections 12.2.5. Using INDEX BY and 12.7.2. Pure and Mixed Results, I came to the conclusion that the result of the INDEX BY example (around line #470) is wrong.

Maybe the DQL statement should start by:
SELECT u, u.status, upper(u.name) nameUpper

(with u instead of u.id)