Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 3cb314e

Browse files
nicolas-grekasnicolas-grekas
committed
Merge branch '2.15.x' into mergeup
* 2.15.x: (23 commits) Fix cloning entities when using lazy-ghost proxies Fixes recomputation of single entity change set when entity contains enum attributes. Due to the fact that originalEntityData contains enum objects and ReflectionEnumProperty::getValue() returns value of enum, comparison of values are always falsy, resulting to update columns value even though it has not changes. Fix code style issues Use absolute references Avoid colon followed by double colon Use correct syntax for references Fix invalid reference syntax Use rst syntax Use internal link Escape pipes Introduce new workflow to test docs Remove lone dash (doctrine#10812) Treat id field proprites same as regular field Move three "Ticket/"-style tests to the right namespace Follow recommendation about multiline type Fix unserialize() errors when running tests on PHP 8.3 (doctrine#10803) Explain `EntityManager::getReference()` peculiarities (doctrine#10800) Upgrade to Psalm 5.13 test: assert `postLoad` has data first distinct() updates QueryBuilder state correctly ...
2 parents 21708e4 + 4978e0e commit 3cb314e

34 files changed

Lines changed: 399 additions & 169 deletions

‎.github/workflows/documentation.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: "Documentation"
2+
3+
on:
4+
pull_request:
5+
branches:
6+
- "*.x"
7+
paths:
8+
- .github/workflows/documentation.yml
9+
- docs/**
10+
push:
11+
branches:
12+
- "*.x"
13+
paths:
14+
- .github/workflows/documentation.yml
15+
- docs/**
16+
17+
jobs:
18+
validate-with-guides:
19+
name: "Validate documentation with phpDocumentor/guides"
20+
runs-on: "ubuntu-22.04"
21+
22+
steps:
23+
- name: "Checkout code"
24+
uses: "actions/checkout@v3"
25+
26+
- name: "Install PHP"
27+
uses: "shivammathur/setup-php@v2"
28+
with:
29+
coverage: "none"
30+
php-version: "8.2"
31+
32+
- name: "Remove existing composer file"
33+
run: "rm composer.json"
34+
35+
- name: "Require phpdocumentor/guides-cli"
36+
run: "composer require --dev phpdocumentor/guides-cli dev-main@dev --no-update"
37+
38+
- name: "Configure minimum stability"
39+
run: "composer config minimum-stability dev"
40+
41+
- name: "Install dependencies with Composer"
42+
uses: "ramsey/composer-install@v2"
43+
with:
44+
dependency-versions: "highest"
45+
46+
- name: "Run guides-cli"
47+
run: "vendor/bin/guides -vvv --no-progress docs/en /tmp/test 2>&1 | ( ! grep WARNING )"

‎composer.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@
4949
"symfony/cache": "^4.4 || ^5.4 || ^6.0",
5050
"symfony/var-exporter": "^4.4 || ^5.4 || ^6.2",
5151
"symfony/yaml": "^3.4 || ^4.0 || ^5.0 || ^6.0",
52-
"vimeo/psalm": "4.30.0 || 5.12.0"
52+
"vimeo/psalm": "4.30.0 || 5.13.0"
5353
},
5454
"conflict": {
5555
"doctrine/annotations": "<1.13 || >= 3.0"

‎docs/en/index.rst‎

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -34,32 +34,32 @@ Mapping Objects onto a Database
3434
-------------------------------
3535

3636
* **Mapping**:
37-
:doc:`Objects <reference/basic-mapping>` |
38-
:doc:`Associations <reference/association-mapping>` |
37+
:doc:`Objects <reference/basic-mapping>` \|
38+
:doc:`Associations <reference/association-mapping>` \|
3939
:doc:`Inheritance <reference/inheritance-mapping>`
4040

4141
* **Drivers**:
42-
:doc:`Docblock Annotations <reference/annotations-reference>` |
43-
:doc:`Attributes <reference/attributes-reference>` |
44-
:doc:`XML <reference/xml-mapping>` |
45-
:doc:`YAML <reference/yaml-mapping>` |
42+
:doc:`Docblock Annotations <reference/annotations-reference>` \|
43+
:doc:`Attributes <reference/attributes-reference>` \|
44+
:doc:`XML <reference/xml-mapping>` \|
45+
:doc:`YAML <reference/yaml-mapping>` \|
4646
:doc:`PHP <reference/php-mapping>`
4747

4848
Working with Objects
4949
--------------------
5050

5151
* **Basic Reference**:
52-
:doc:`Entities <reference/working-with-objects>` |
53-
:doc:`Associations <reference/working-with-associations>` |
52+
:doc:`Entities <reference/working-with-objects>` \|
53+
:doc:`Associations <reference/working-with-associations>` \|
5454
:doc:`Events <reference/events>`
5555

5656
* **Query Reference**:
57-
:doc:`DQL <reference/dql-doctrine-query-language>` |
58-
:doc:`QueryBuilder <reference/query-builder>` |
57+
:doc:`DQL <reference/dql-doctrine-query-language>` \|
58+
:doc:`QueryBuilder <reference/query-builder>` \|
5959
:doc:`Native SQL <reference/native-sql>`
6060

6161
* **Internals**:
62-
:doc:`Internals explained <reference/unitofwork>` |
62+
:doc:`Internals explained <reference/unitofwork>` \|
6363
:doc:`Associations <reference/unitofwork-associations>`
6464

6565
Advanced Topics
@@ -102,20 +102,20 @@ Cookbook
102102
--------
103103

104104
* **Patterns**:
105-
:doc:`Aggregate Fields <cookbook/aggregate-fields>` |
106-
:doc:`Decorator Pattern <cookbook/decorator-pattern>` |
105+
:doc:`Aggregate Fields <cookbook/aggregate-fields>` \|
106+
:doc:`Decorator Pattern <cookbook/decorator-pattern>` \|
107107
:doc:`Strategy Pattern <cookbook/strategy-cookbook-introduction>`
108108

109109
* **DQL Extension Points**:
110-
:doc:`DQL Custom Walkers <cookbook/dql-custom-walkers>` |
110+
:doc:`DQL Custom Walkers <cookbook/dql-custom-walkers>` \|
111111
:doc:`DQL User-Defined-Functions <cookbook/dql-user-defined-functions>`
112112

113113
* **Implementation**:
114-
:doc:`Array Access <cookbook/implementing-arrayaccess-for-domain-objects>` |
115-
:doc:`Notify ChangeTracking Example <cookbook/implementing-the-notify-changetracking-policy>` |
116-
:doc:`Working with DateTime <cookbook/working-with-datetime>` |
117-
:doc:`Validation <cookbook/validation-of-entities>` |
118-
:doc:`Entities in the Session <cookbook/entities-in-session>` |
114+
:doc:`Array Access <cookbook/implementing-arrayaccess-for-domain-objects>` \|
115+
:doc:`Notify ChangeTracking Example <cookbook/implementing-the-notify-changetracking-policy>` \|
116+
:doc:`Working with DateTime <cookbook/working-with-datetime>` \|
117+
:doc:`Validation <cookbook/validation-of-entities>` \|
118+
:doc:`Entities in the Session <cookbook/entities-in-session>` \|
119119
:doc:`Keeping your Modules independent <cookbook/resolve-target-entity-listener>`
120120

121121
* **Hidden Gems**

‎docs/en/reference/advanced-configuration.rst‎

Lines changed: 31 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -311,10 +311,12 @@ Reference Proxies
311311

312312
The method ``EntityManager#getReference($entityName, $identifier)``
313313
lets you obtain a reference to an entity for which the identifier
314-
is known, without loading that entity from the database. This is
315-
useful, for example, as a performance enhancement, when you want to
316-
establish an association to an entity for which you have the
317-
identifier. You could simply do this:
314+
is known, without necessarily loading that entity from the database.
315+
This is useful, for example, as a performance enhancement, when you
316+
want to establish an association to an entity for which you have the
317+
identifier.
318+
319+
Consider the following example:
318320

319321
.. code-block:: php
320322
@@ -324,15 +326,33 @@ identifier. You could simply do this:
324326
$item = $em->getReference('MyProject\Model\Item', $itemId);
325327
$cart->addItem($item);
326328
327-
Here, we added an Item to a Cart without loading the Item from the
328-
database. If you access any state that isn't yet available in the
329-
Item instance, the proxying mechanism would fully initialize the
330-
object's state transparently from the database. Here
331-
$item is actually an instance of the proxy class that was generated
332-
for the Item class but your code does not need to care. In fact it
333-
**should not care**. Proxy objects should be transparent to your
329+
Whether the object being returned from ``EntityManager#getReference()``
330+
is a proxy or a direct instance of the entity class may depend on different
331+
factors, including whether the entity has already been loaded into memory
332+
or entity inheritance being used. But your code does not need to care
333+
and in fact it **should not care**. Proxy objects should be transparent to your
334334
code.
335335

336+
When using the ``EntityManager#getReference()`` method, you need to be aware
337+
of a few peculiarities.
338+
339+
At the best case, the ORM can avoid querying the database at all. But, that
340+
also means that this method will not throw an exception when an invalid value
341+
for the ``$identifier`` parameter is passed. ``$identifier`` values are
342+
not checked and there is no guarantee that the requested entity instance even
343+
exists – the method will still return a proxy object.
344+
345+
Its only when the proxy has to be fully initialized or associations cannot
346+
be written to the database that invalid ``$identifier`` values may lead to
347+
exceptions.
348+
349+
The ``EntityManager#getReference()`` is mostly useful when you only
350+
need a reference to some entity to make an association, like in the example
351+
above. In that case, it can save you from loading data from the database
352+
that you don't need. But remember – as soon as you read any property values
353+
besides those making up the ID, a database request will be made to initialize
354+
all fields.
355+
336356
Association proxies
337357
~~~~~~~~~~~~~~~~~~~
338358

‎docs/en/reference/architecture.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ persistent entity state and mapping information for its subclasses,
102102
but which is not itself an entity.
103103

104104
Mapped superclasses are explained in greater detail in the chapter
105-
on :doc:`inheritance mapping <reference/inheritance-mapping>`.
105+
on :doc:`inheritance mapping </reference/inheritance-mapping>`.
106106

107107
Transient Classes
108108
~~~~~~~~~~~~~~~~~

‎docs/en/reference/basic-mapping.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -460,7 +460,7 @@ Here is the list of possible generation strategies:
460460
a new entity is passed to ``EntityManager#persist``. NONE is the
461461
same as leaving off the ``#[GeneratedValue]`` entirely.
462462
- ``CUSTOM``: With this option, you can use the ``#[CustomIdGenerator]`` attribute.
463-
It will allow you to pass a :doc:`class of your own to generate the identifiers.<_annref_customidgenerator>`
463+
It will allow you to pass a :ref:`class of your own to generate the identifiers.<annref_customidgenerator>`
464464

465465
Sequence Generator
466466
^^^^^^^^^^^^^^^^^^

‎docs/en/reference/configuration.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ Inside the ``ORMSetup`` methods several assumptions are made:
104104
In order to have ``ORMSetup`` configure the cache automatically, the library ``symfony/cache``
105105
has to be installed as a dependency.
106106

107-
If you want to configure Doctrine in more detail, take a look at the :doc:`Advanced Configuration <reference/advanced-configuration>` section.
107+
If you want to configure Doctrine in more detail, take a look at the :doc:`Advanced Configuration </reference/advanced-configuration>` section.
108108

109109
.. note::
110110

‎docs/en/reference/dql-doctrine-query-language.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1336,8 +1336,8 @@ There are situations when a query you want to execute returns a
13361336
very large result-set that needs to be processed. All the
13371337
previously described hydration modes completely load a result-set
13381338
into memory which might not be feasible with large result sets. See
1339-
the `Batch Processing <batch-processing.html>`_ section on details how
1340-
to iterate large result sets.
1339+
the :doc:`Batch Processing </reference/batch-processing>` section on
1340+
details how to iterate large result sets.
13411341

13421342
Functions
13431343
~~~~~~~~~

‎docs/en/reference/improving-performance.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ Apply Best Practices
9191
A lot of the points mentioned in the Best Practices chapter will
9292
also positively affect the performance of Doctrine.
9393

94-
See :doc:`Best Practices <reference/best-practices>`
94+
See :doc:`Best Practices </reference/best-practices>`
9595

9696
Change Tracking policies
9797
------------------------

‎docs/en/reference/inheritance-mapping.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ have to be used.
3535
superclass, since they require the "many" side to hold the foreign
3636
key.
3737

38-
It is, however, possible to use the :doc:`ResolveTargetEntityListener <cookbook/resolve-target-entity-listener>`
38+
It is, however, possible to use the :doc:`ResolveTargetEntityListener </cookbook/resolve-target-entity-listener>`
3939
to replace references to a mapped superclass with an entity class at runtime.
4040
As long as there is only one entity subclass inheriting from the mapped
4141
superclass and all references to the mapped superclass are resolved to that
@@ -45,7 +45,7 @@ have to be used.
4545
.. warning::
4646

4747
At least when using attributes or annotations to specify your mapping,
48-
it _seems_ as if you could inherit from a base class that is neither
48+
it *seems* as if you could inherit from a base class that is neither
4949
an entity nor a mapped superclass, but has properties with mapping configuration
5050
on them that would also be used in the inheriting class.
5151

@@ -60,7 +60,7 @@ have to be used.
6060
You may be tempted to use traits to mix mapped fields or relationships
6161
into your entity classes to circumvent some of the limitations of
6262
mapped superclasses. Before doing that, please read the section on traits
63-
in the :doc:`Limitations and Known Issues <reference/limitations-and-known-issues>` chapter.
63+
in the :doc:`Limitations and Known Issues </reference/limitations-and-known-issues>` chapter.
6464

6565
Example:
6666

@@ -380,7 +380,7 @@ It is not supported to use overrides in entity inheritance scenarios.
380380
.. note::
381381
382382
When using traits, make sure not to miss the warnings given in the
383-
:doc:`Limitations and Known Issues<reference/limitations-and-known-issues>` chapter.
383+
:doc:`Limitations and Known Issues</reference/limitations-and-known-issues>` chapter.
384384
385385
386386
Association Override

0 commit comments

Comments
 (0)