doctrine-orm-doc 2.4.6-1+deb8u1 / usr / share / doc / php-doctrine-orm / html / reference / change-tracking-policies.html

This file is indexed.

/usr/share/doc/php-doctrine-orm/html/reference/change-tracking-policies.html is in doctrine-orm-doc 2.4.6-1+deb8u1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below. 

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>18. Change Tracking Policies &mdash; Doctrine 2 ORM 2 documentation</title>
    <link rel="stylesheet" href="../_static/bootstrap/css/bootstrap.min.css" type="text/css" />
    <link rel="stylesheet" href="../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="../_static/layout.css" type="text/css" />
    <link rel="stylesheet" href="../_static/configurationblock.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '2',
        COLLAPSE_MODINDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>

    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/configurationblock.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/configurationblock.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/configurationblock.js"></script>
    <script src="../_static/bootstrap/js/bootstrap.min.js"></script>

    <script type="text/javascript">
    <!--
        $(document).ready(function() {
            $("#versions").change(function() {
                var docsUrl = $(this).val();
                window.location.href = docsUrl;
            });
        });
    -->
    </script>
    <link rel="shortcut icon" href="../_static/doctrine.ico"/>
    <link rel="top" title="Doctrine 2 ORM 2 documentation" href="../index.html" />
    <link rel="next" title="19. Partial Objects" href="partial-objects.html" />
    <link rel="prev" title="17. Native SQL" href="native-sql.html" /> 
  </head>
  <body>
    <div id="wrapper">
      <div id="header">
        <h1 id="h1title"></h1>
        <div id="logo">
          <a href="http://www.doctrine-project.org/">Doctrine - PHP Database Libraries</a>
        </div>
      </div>
      <div id="nav" class="cls">
        <div class="tl cls">
          <ul>
            <li><a target="_top" href="/">home</a></li>
            <li><a class="" target="_top" href="http://www.doctrine-project.org/about">about</a></li>
            <li><a class="" target="_top" href="http://www.doctrine-project.org/projects.html">projects</a></li>
            <li><a class="" target="_top" href="http://www.doctrine-project.org/projects/orm">orm</a></li>
            <li><a class="" target="_top" href="http://www.doctrine-project.org/projects/dbal">dbal</a></li>
            <li><a class="" target="_top" href="http://www.doctrine-project.org/blog">blog</a></li>
            <li><a class="" target="_top" href="http://www.doctrine-project.org/jira">development</a></li>
            <li><a class="" target="_top" href="http://www.doctrine-project.org/contribute">contribute</a></li>
            <li><a class="" target="_top" href="http://www.doctrine-project.org/community">community</a></li>
          </ul>
        </div>
      </div>
      <div id="content" class="cls">
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="partial-objects.html" title="19. Partial Objects"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="native-sql.html" title="17. Native SQL"
             accesskey="P">previous</a> |</li>
        <li><a href="/">Doctrine Homepage</a> &raquo;</li>
        <li><a href="../index.html">Doctrine 2 ORM 2 documentation</a> &raquo;</li> 
      </ul>
    </div>  

        <div class="document">
            <div class="documentwrapper">
                <div class="bodywrapper">

              <div class="body" >
                
  <div class="section" id="change-tracking-policies">
<h1>18. Change Tracking Policies<a class="headerlink" href="#change-tracking-policies" title="Permalink to this headline"></a></h1>
<p>Change tracking is the process of determining what has changed in
managed entities since the last time they were synchronized with
the database.</p>
<p>Doctrine provides 3 different change tracking policies, each having
its particular advantages and disadvantages. The change tracking
policy can be defined on a per-class basis (or more precisely,
per-hierarchy).</p>
<div class="section" id="deferred-implicit">
<h2>18.1. Deferred Implicit<a class="headerlink" href="#deferred-implicit" title="Permalink to this headline"></a></h2>
<p>The deferred implicit policy is the default change tracking policy
and the most convenient one. With this policy, Doctrine detects the
changes by a property-by-property comparison at commit time and
also detects changes to entities or new entities that are
referenced by other managed entities (&#8220;persistence by
reachability&#8221;). Although the most convenient policy, it can have
negative effects on performance if you are dealing with large units
of work (see &#8220;Understanding the Unit of Work&#8221;). Since Doctrine
can&#8217;t know what has changed, it needs to check all managed entities
for changes every time you invoke EntityManager#flush(), making
this operation rather costly.</p>
</div>
<div class="section" id="deferred-explicit">
<h2>18.2. Deferred Explicit<a class="headerlink" href="#deferred-explicit" title="Permalink to this headline"></a></h2>
<p>The deferred explicit policy is similar to the deferred implicit
policy in that it detects changes through a property-by-property
comparison at commit time. The difference is that Doctrine 2 only
considers entities that have been explicitly marked for change detection
through a call to EntityManager#persist(entity) or through a save
cascade. All other entities are skipped. This policy therefore
gives improved performance for larger units of work while
sacrificing the behavior of &#8220;automatic dirty checking&#8221;.</p>
<p>Therefore, flush() operations are potentially cheaper with this
policy. The negative aspect this has is that if you have a rather
large application and you pass your objects through several layers
for processing purposes and business tasks you may need to track
yourself which entities have changed on the way so you can pass
them to EntityManager#persist().</p>
<p>This policy can be configured as follows:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @Entity</span>
<span class="sd"> * @ChangeTrackingPolicy(&quot;DEFERRED_EXPLICIT&quot;)</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">User</span>
<span class="p">{</span>
    <span class="c1">// ...</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="notify">
<h2>18.3. Notify<a class="headerlink" href="#notify" title="Permalink to this headline"></a></h2>
<p>This policy is based on the assumption that the entities notify
interested listeners of changes to their properties. For that
purpose, a class that wants to use this policy needs to implement
the <tt class="docutils literal"><span class="pre">NotifyPropertyChanged</span></tt> interface from the Doctrine
namespace. As a guideline, such an implementation can look as
follows:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="k">use</span> <span class="nx">Doctrine\Common\NotifyPropertyChanged</span><span class="p">,</span>
    <span class="nx">Doctrine\Common\PropertyChangedListener</span><span class="p">;</span>

<span class="sd">/**</span>
<span class="sd"> * @Entity</span>
<span class="sd"> * @ChangeTrackingPolicy(&quot;NOTIFY&quot;)</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">MyEntity</span> <span class="k">implements</span> <span class="nx">NotifyPropertyChanged</span>
<span class="p">{</span>
    <span class="c1">// ...</span>

    <span class="k">private</span> <span class="nv">$_listeners</span> <span class="o">=</span> <span class="k">array</span><span class="p">();</span>

    <span class="k">public</span> <span class="k">function</span> <span class="nf">addPropertyChangedListener</span><span class="p">(</span><span class="nx">PropertyChangedListener</span> <span class="nv">$listener</span><span class="p">)</span>
    <span class="p">{</span>
        <span class="nv">$this</span><span class="o">-&gt;</span><span class="na">_listeners</span><span class="p">[]</span> <span class="o">=</span> <span class="nv">$listener</span><span class="p">;</span>
    <span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Then, in each property setter of this class or derived classes, you
need to notify all the <tt class="docutils literal"><span class="pre">PropertyChangedListener</span></tt> instances. As an
example we add a convenience method on <tt class="docutils literal"><span class="pre">MyEntity</span></tt> that shows this
behaviour:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="c1">// ...</span>

<span class="k">class</span> <span class="nc">MyEntity</span> <span class="k">implements</span> <span class="nx">NotifyPropertyChanged</span>
<span class="p">{</span>
    <span class="c1">// ...</span>

    <span class="k">protected</span> <span class="k">function</span> <span class="nf">_onPropertyChanged</span><span class="p">(</span><span class="nv">$propName</span><span class="p">,</span> <span class="nv">$oldValue</span><span class="p">,</span> <span class="nv">$newValue</span><span class="p">)</span>
    <span class="p">{</span>
        <span class="k">if</span> <span class="p">(</span><span class="nv">$this</span><span class="o">-&gt;</span><span class="na">_listeners</span><span class="p">)</span> <span class="p">{</span>
            <span class="k">foreach</span> <span class="p">(</span><span class="nv">$this</span><span class="o">-&gt;</span><span class="na">_listeners</span> <span class="k">as</span> <span class="nv">$listener</span><span class="p">)</span> <span class="p">{</span>
                <span class="nv">$listener</span><span class="o">-&gt;</span><span class="na">propertyChanged</span><span class="p">(</span><span class="nv">$this</span><span class="p">,</span> <span class="nv">$propName</span><span class="p">,</span> <span class="nv">$oldValue</span><span class="p">,</span> <span class="nv">$newValue</span><span class="p">);</span>
            <span class="p">}</span>
        <span class="p">}</span>
    <span class="p">}</span>

    <span class="k">public</span> <span class="k">function</span> <span class="nf">setData</span><span class="p">(</span><span class="nv">$data</span><span class="p">)</span>
    <span class="p">{</span>
        <span class="k">if</span> <span class="p">(</span><span class="nv">$data</span> <span class="o">!=</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="na">data</span><span class="p">)</span> <span class="p">{</span>
            <span class="nv">$this</span><span class="o">-&gt;</span><span class="na">_onPropertyChanged</span><span class="p">(</span><span class="s1">&#39;data&#39;</span><span class="p">,</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="na">data</span><span class="p">,</span> <span class="nv">$data</span><span class="p">);</span>
            <span class="nv">$this</span><span class="o">-&gt;</span><span class="na">data</span> <span class="o">=</span> <span class="nv">$data</span><span class="p">;</span>
        <span class="p">}</span>
    <span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>You have to invoke <tt class="docutils literal"><span class="pre">_onPropertyChanged</span></tt> inside every method that
changes the persistent state of <tt class="docutils literal"><span class="pre">MyEntity</span></tt>.</p>
<p>The check whether the new value is different from the old one is
not mandatory but recommended. That way you also have full control
over when you consider a property changed.</p>
<p>The negative point of this policy is obvious: You need implement an
interface and write some plumbing code. But also note that we tried
hard to keep this notification functionality abstract. Strictly
speaking, it has nothing to do with the persistence layer and the
Doctrine ORM or DBAL. You may find that property notification
events come in handy in many other scenarios as well. As mentioned
earlier, the <tt class="docutils literal"><span class="pre">Doctrine\Common</span></tt> namespace is not that evil and
consists solely of very small classes and interfaces that have
almost no external dependencies (none to the DBAL and none to the
ORM) and that you can easily take with you should you want to swap
out the persistence layer. This change tracking policy does not
introduce a dependency on the Doctrine DBAL/ORM or the persistence
layer.</p>
<p>The positive point and main advantage of this policy is its
effectiveness. It has the best performance characteristics of the 3
policies with larger units of work and a flush() operation is very
cheap when nothing has changed.</p>
</div>
</div>


              </div>
                </div>

            </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
             
            <div id="searchbox" style="">
              <h3>Search</h3>
                <form class="search" action="http://readthedocs.org/search/project/" method="get">
                  <input type="text" name="q" size="18">
                  <input type="submit" value="Go">
                  <input type="hidden" name="selected_facets" value="project:">
                </form>
            </div>
            <h3><a href="../index.html">Table Of Contents</a></h3>
            <ul>
<li><a class="reference internal" href="#">18. Change Tracking Policies</a><ul>
<li><a class="reference internal" href="#deferred-implicit">18.1. Deferred Implicit</a></li>
<li><a class="reference internal" href="#deferred-explicit">18.2. Deferred Explicit</a></li>
<li><a class="reference internal" href="#notify">18.3. Notify</a></li>
</ul>
</li>
</ul>

            <h4>Previous topic</h4>
            <p class="topless"><a href="native-sql.html"
                                  title="previous chapter">17. Native SQL</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="partial-objects.html"
                                  title="next chapter">19. Partial Objects</a></p>
            <h3>This Page</h3>
            <ul class="this-page-menu">
              <li><a href="../_sources/reference/change-tracking-policies.txt"
                     rel="nofollow">Show Source</a></li>
            </ul>
        </div>
      </div>
          <div class="clearer"></div>
        </div>
          <div class="footer">
              &copy; Copyright 2010-12, Doctrine Project Team.
              Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2.3.
            <br/>
            <a target="_BLANK" href="http://www.servergrove.com"><img src="../_static/servergrove.jpg" /></a>      <br/><br/>
            <form action="https://www.paypal.com/cgi-bin/webscr" method="post">
              <input type="hidden" name="cmd" value="_s-xclick" />
              <input type="hidden" name="hosted_button_id" value="BAE2E3XANQ77Y" />
              <input type="Submit" value="Donate via PayPal" />
            </form>
          </div>
      </div>

      <div id="bot-rcnr">
        <div class="tl"><!-- corner --></div>
      </div>
    </div>

  <a class="githublink" href="http://github.com/doctrine">Fork me on GitHub</a>
  </body>
</html>

APT Browse - Built by Thomas Orozco.