diff --git a/cookbook/en.rst b/cookbook/en.rst deleted file mode 100644 index 2c5786b1d..000000000 --- a/cookbook/en.rst +++ /dev/null @@ -1,34 +0,0 @@ -Getting Started XML-Edition -=========================== - -Implementing ArrayAccess for domain objects -=========================================== - -Implementing the NOTIFY change-tracking policy -============================================== - -Validation of Entities -====================== - -Implementing wakeup or clone -============================ - -Integrating with CodeIgniter -============================ - -DQL Custom Walkers -================== - -DQL User Defined Functions -========================== - -SQL Table Prefixes -================== - -Strategy Cookbook Introduction -============================== - -Aggregate Fields -================ - - diff --git a/cookbook/en.txt b/cookbook/en.txt deleted file mode 100644 index 6a77ba99d..000000000 --- a/cookbook/en.txt +++ /dev/null @@ -1,11 +0,0 @@ -# Getting Started XML-Edition -# Implementing ArrayAccess for domain objects -# Implementing the NOTIFY change-tracking policy -# Validation of Entities -# Implementing wakeup or clone -# Integrating with CodeIgniter -# DQL Custom Walkers -# DQL User Defined Functions -# SQL Table Prefixes -# Strategy Cookbook Introduction -# Aggregate Fields \ No newline at end of file diff --git a/cookbook/en/Makefile b/cookbook/en/Makefile deleted file mode 100644 index 987598317..000000000 --- a/cookbook/en/Makefile +++ /dev/null @@ -1,89 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Doctrine2ORMCookbook.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Doctrine2ORMCookbook.qhc" - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ - "run these through (pdf)latex." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff --git a/cookbook/en/conf.py b/cookbook/en/conf.py deleted file mode 100644 index 18997a35d..000000000 --- a/cookbook/en/conf.py +++ /dev/null @@ -1,196 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Doctrine 2 ORM Cookbook documentation build configuration file, created by -# sphinx-quickstart on Mon Nov 1 21:13:13 2010. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys, os - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.append(os.path.abspath('.')) - -# -- General configuration ----------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'Doctrine 2 ORM Cookbook' -copyright = u'2010, Doctrine Project Team' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '2.0' -# The full version, including alpha/beta/rc tags. -release = '2.0.0-BETA4' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -language = 'en' - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of documents that shouldn't be included in the build. -#unused_docs = [] - -# List of directories, relative to source directory, that shouldn't be searched -# for source files. -exclude_trees = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -highlight_language = 'php' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. Major themes that come with -# Sphinx are currently 'default' and 'sphinxdoc'. -html_theme = 'default' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_use_modindex = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = '' - -# Output file base name for HTML help builder. -htmlhelp_basename = 'Doctrine2ORMCookbookdoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -# The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'Doctrine2ORMCookbook.tex', u'Doctrine 2 ORM Cookbook Documentation', - u'Doctrine Project Team', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# Additional stuff for the LaTeX preamble. -#latex_preamble = '' - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_use_modindex = True diff --git a/cookbook/en/index.rst b/cookbook/en/index.rst deleted file mode 100644 index 4c4be6adc..000000000 --- a/cookbook/en/index.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. Doctrine 2 ORM Cookbook documentation master file, created by - sphinx-quickstart on Mon Nov 1 21:13:13 2010. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to Doctrine 2 ORM Cookbook's documentation! -=================================================== - -Contents: - -.. toctree:: - :maxdepth: 2 - - getting-started-xml-edition - implementing-arrayaccess-for-domain-objects - implementing-the-notify-changetracking-policy - validations-of-entities - implementing-wakeup-or-clone - integrating-with-codeigniter - dql-custom-walkers - dql-user-defined-functions - sql-table-prefixes - strategy-cookbook-introdution - aggregates-fields - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/cookbook/en/make.bat b/cookbook/en/make.bat deleted file mode 100644 index 9f1a938d9..000000000 --- a/cookbook/en/make.bat +++ /dev/null @@ -1,113 +0,0 @@ -@ECHO OFF - -REM Command file for Sphinx documentation - -set SPHINXBUILD=sphinx-build -set BUILDDIR=_build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . -if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% -) - -if "%1" == "" goto help - -if "%1" == "help" ( - :help - echo.Please use `make ^` where ^ is one of - echo. html to make standalone HTML files - echo. dirhtml to make HTML files named index.html in directories - echo. pickle to make pickle files - echo. json to make JSON files - echo. htmlhelp to make HTML files and a HTML help project - echo. qthelp to make HTML files and a qthelp project - echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. changes to make an overview over all changed/added/deprecated items - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* - goto end -) - -if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end -) - -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - echo. - echo.Build finished; now you can process the JSON files. - goto end -) - -if "%1" == "htmlhelp" ( - %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - echo. - echo.Build finished; now you can run HTML Help Workshop with the ^ -.hhp project file in %BUILDDIR%/htmlhelp. - goto end -) - -if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - echo. - echo.Build finished; now you can run "qcollectiongenerator" with the ^ -.qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Doctrine2ORMCookbook.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Doctrine2ORMCookbook.ghc - goto end -) - -if "%1" == "latex" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - echo. - echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - echo. - echo.The overview file is in %BUILDDIR%/changes. - goto end -) - -if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - echo. - echo.Link check complete; look for any errors in the above output ^ -or in %BUILDDIR%/linkcheck/output.txt. - goto end -) - -if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - echo. - echo.Testing of doctests in the sources finished, look at the ^ -results in %BUILDDIR%/doctest/output.txt. - goto end -) - -:end diff --git a/manual/en/Makefile b/en/Makefile similarity index 100% rename from manual/en/Makefile rename to en/Makefile diff --git a/en/_templates/layout.html b/en/_templates/layout.html new file mode 100644 index 000000000..3380dbe13 --- /dev/null +++ b/en/_templates/layout.html @@ -0,0 +1,198 @@ +{%- block doctype -%} + +{%- endblock %} +{%- set reldelim1 = reldelim1 is not defined and ' »' or reldelim1 %} +{%- set reldelim2 = reldelim2 is not defined and ' |' or reldelim2 %} +{%- set url_root = pathto('', 1) %} +{%- if url_root == '#' %}{% set url_root = '' %}{% endif %} + +{%- macro relbar() %} +
+

{{ _('Navigation') }}

+
    + {%- for rellink in rellinks %} +
  • + {{ rellink[3] }} + {%- if not loop.first %}{{ reldelim2 }}{% endif %}
    • + {%- endfor %} + {%- block rootrellink %} +
  • {{ shorttitle|e }}{{ reldelim1 }}
    • + {%- endblock %} + {%- for parent in parents %} +
  • {{ parent.title }}{{ reldelim1 }}
    • + {%- endfor %} + {%- block relbaritems %} {% endblock %} +
+
+{%- endmacro %} + +{%- macro sidebar() %} + {%- if not embedded %}{% if not theme_nosidebar|tobool %} +
+
+ {%- block sidebarlogo %} + {%- if logo %} + + {%- endif %} + {%- endblock %} + {%- block sidebartoc %} + {%- if display_toc %} +

{{ _('Table Of Contents') }}

+ {{ toc }} + {%- endif %} + {%- endblock %} + {%- block sidebarrel %} + {%- if prev %} +

{{ _('Previous topic') }}

+

{{ prev.title }}

+ {%- endif %} + {%- if next %} +

{{ _('Next topic') }}

+

{{ next.title }}

+ {%- endif %} + {%- endblock %} + {%- block sidebarsourcelink %} + {%- if show_source and has_source and sourcename %} +

{{ _('This Page') }}

+ + {%- endif %} + {%- endblock %} + {%- if customsidebar %} + {% include customsidebar %} + {%- endif %} + {%- block sidebarsearch %} + {%- if pagename != "search" %} + + + {%- endif %} + {%- endblock %} +
+
+ {%- endif %}{% endif %} +{%- endmacro %} + + + + + {{ metatags }} + {%- if not embedded and docstitle %} + {%- set titlesuffix = " — "|safe + docstitle|e %} + {%- else %} + {%- set titlesuffix = "" %} + {%- endif %} + {{ title|striptags }}{{ titlesuffix }} + + + {%- if not embedded %} + + {%- for scriptfile in script_files %} + + {%- endfor %} + {%- if use_opensearch %} + + {%- endif %} + {%- if favicon %} + + {%- endif %} + {%- endif %} +{%- block linktags %} + {%- if hasdoc('about') %} + + {%- endif %} + {%- if hasdoc('genindex') %} + + {%- endif %} + {%- if hasdoc('search') %} + + {%- endif %} + {%- if hasdoc('copyright') %} + + {%- endif %} + + {%- if parents %} + + {%- endif %} + {%- if next %} + + {%- endif %} + {%- if prev %} + + {%- endif %} +{%- endblock %} +{%- block extrahead %} {% endblock %} + + +{%- block header %}{% endblock %} + +{%- block relbar1 %}{{ relbar() }}{% endblock %} + +{%- block sidebar1 %} {# possible location for sidebar #} {% endblock %} + +
+{%- block document %} +
+ {%- if not embedded %}{% if not theme_nosidebar|tobool %} +
+ {%- endif %}{% endif %} +
+ {% block body %} {% endblock %} +
+ {%- if not embedded %}{% if not theme_nosidebar|tobool %} +
+ {%- endif %}{% endif %} +
+{%- endblock %} + +{%- block sidebar2 %}{{ sidebar() }}{% endblock %} +
+
+ +{%- block relbar2 %}{{ relbar() }}{% endblock %} + +{%- block footer %} +
+ {%- if hasdoc('copyright') %} + {% trans path=pathto('copyright'), copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} + {%- else %} + {% trans copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} + {%- endif %} + {%- if last_updated %} + {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} + {%- endif %} + {%- if show_sphinx %} + {% trans sphinx_version=sphinx_version|e %}Created using Sphinx {{ sphinx_version }}.{% endtrans %} + {%- endif %} +
+{%- endblock %} + + diff --git a/manual/en/conf.py b/en/conf.py similarity index 95% rename from manual/en/conf.py rename to en/conf.py index b972b640f..7069824f1 100644 --- a/manual/en/conf.py +++ b/en/conf.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- # # Doctrine 2 ORM documentation build configuration file, created by -# sphinx-quickstart on Mon Nov 1 21:19:39 2010. +# sphinx-quickstart on Fri Dec 3 18:10:24 2010. # # This file is execfile()d with the current directory set to its containing dir. # @@ -38,7 +38,7 @@ master_doc = 'index' # General information about the project. project = u'Doctrine 2 ORM' -copyright = u'2010, Roman Borschel, Guilherme Blanco, Benjamin Eberlei, Jonathan Wage' +copyright = u'2010, Doctrine Project Team' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -47,11 +47,11 @@ copyright = u'2010, Roman Borschel, Guilherme Blanco, Benjamin Eberlei, Jonathan # The short X.Y version. version = '2.0' # The full version, including alpha/beta/rc tags. -release = '2.0.0-BETA4' +release = '2.0.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -language = 'en' +language = 'php' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: @@ -78,13 +78,11 @@ exclude_trees = ['_build'] # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. -#show_authors = False +show_authors = True # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' -highlight_language = 'php' - # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] @@ -175,7 +173,7 @@ htmlhelp_basename = 'Doctrine2ORMdoc' # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ ('index', 'Doctrine2ORM.tex', u'Doctrine 2 ORM Documentation', - u'Roman Borschel, Guilherme Blanco, Benjamin Eberlei, Jonathan Wage', 'manual'), + u'Doctrine Project Team', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of diff --git a/cookbook/en/aggregate-fields.rst b/en/cookbook/aggregate-fields.rst similarity index 97% rename from cookbook/en/aggregate-fields.rst rename to en/cookbook/aggregate-fields.rst index ef91a4d62..521f5d025 100644 --- a/cookbook/en/aggregate-fields.rst +++ b/en/cookbook/aggregate-fields.rst @@ -1,6 +1,8 @@ Aggregate Fields ================ +.. sectionauthor:: Benjamin Eberlei + You will often come across the requirement to display aggregate values of data that can be computed by using the MIN, MAX, COUNT or SUM SQL functions. For any ORM this is a tricky issue @@ -27,7 +29,7 @@ added on the ``Entry`` object. Our entities look like: -:: +.. code-block:: php ``Entry`` relation with this method: -:: +.. code-block:: php + 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 @@ -58,7 +60,7 @@ Say you have a blog and posts all with one category and one author. A query for the front-page or any archive page might look something like: -.. code-clock:: sql +.. code-block:: sql SELECT p, c, a FROM BlogPost p JOIN p.category c JOIN p.author a WHERE ... @@ -72,7 +74,7 @@ posts that match the WHERE clause of this query to be able to predict the number of pages to show to the user. A draft of the DQL query for pagination would look like: -.. code-clock:: sql +.. code-block:: sql SELECT count(DISTINCT p.id) FROM BlogPost p JOIN p.category c JOIN p.author a WHERE ... @@ -80,7 +82,7 @@ Now you could go and write each of these queries by hand, or you can use a tree walker to modify the AST for you. Lets see how the API would look for this use-case: -:: +.. code-block:: php + By default DQL supports a limited subset of all the vendor-specific SQL functions common between all the vendors. However in many cases once you have decided on a specific database vendor, you will never @@ -8,13 +10,12 @@ change it during the life of your project. This decision for a specific vendor potentially allows you to make use of powerful SQL features that are unique to the vendor. - **Note** - - It is worth to mention that Doctrine 2 also allows you to handwrite - your SQL instead of extending the DQL parser, which is sort of an - advanced extension point. You can map arbitrary SQL to your objects - and gain access to vendor specific functionalities using the - ``EntityManager#createNativeQuery()`` API. +It is worth to mention that Doctrine 2 also allows you to handwrite +your SQL instead of extending the DQL parser. Extending DQL is sort of an +advanced extension point. You can map arbitrary SQL to your objects +and gain access to vendor specific functionalities using the +``EntityManager#createNativeQuery()`` API as described in +the :doc:`Native Query <../reference/native-sql>` chapter. The DQL Parser has hooks to register functions that can then be @@ -37,7 +38,7 @@ Registering your own DQL functions You can register your functions adding them to the ORM configuration: -:: +.. code-block:: php p.created diff --git a/cookbook/en/implementing-arrayaccess-for-domain-objects.rst b/en/cookbook/implementing-arrayaccess-for-domain-objects.rst similarity index 96% rename from cookbook/en/implementing-arrayaccess-for-domain-objects.rst rename to en/cookbook/implementing-arrayaccess-for-domain-objects.rst index aeb9a7ada..4eb2b717b 100644 --- a/cookbook/en/implementing-arrayaccess-for-domain-objects.rst +++ b/en/cookbook/implementing-arrayaccess-for-domain-objects.rst @@ -1,6 +1,8 @@ Implementing ArrayAccess for Domain Objects =========================================== +.. sectionauthor:: Roman Borschel (roman@code-factory.org) + This recipe will show you how to implement ArrayAccess for your domain objects in order to allow more uniform access, for example in templates. In these examples we will implement ArrayAccess on a @@ -18,7 +20,7 @@ at runtime. Note that this implementation has 2 main caveats: - It will not work with private fields - It will not go through any getters/setters -:: +.. code-block:: php `_, it is usually not allowed for an entity to implement ``__wakeup`` @@ -15,7 +17,7 @@ Safely implementing \_\_wakeup To safely implement ``__wakeup``, simply enclose your implementation code in an identity check as follows: -:: +.. code-block:: php setMetadataCacheImpl($cache); + $driverImpl = $config->newDefaultAnnotationDriver(array(APPPATH.'models/Entities')); + $config->setMetadataDriverImpl($driverImpl); + $config->setQueryCacheImpl($cache); // Proxy configuration @@ -115,7 +118,7 @@ Now to use it Whenever you need a reference to the entity manager inside one of your controllers, views, or models you can do this: -:: +.. code-block:: php doctrine->em; @@ -126,7 +129,7 @@ EntityManager do your Doctrine 2.0 voodoo as normal. Note: If you do not choose to autoload the Doctrine library, you will need to put this line before you get a reference to it: -:: +.. code-block:: php load->library('doctrine'); diff --git a/cookbook/en/sql-table-prefixes.rst b/en/cookbook/sql-table-prefixes.rst similarity index 98% rename from cookbook/en/sql-table-prefixes.rst rename to en/cookbook/sql-table-prefixes.rst index 8f3ee3809..7e1579286 100644 --- a/cookbook/en/sql-table-prefixes.rst +++ b/en/cookbook/sql-table-prefixes.rst @@ -20,7 +20,7 @@ DoctrineExtensions namespace. You create this file in your library/DoctrineExtensions directory, but will need to set up appropriate autoloaders. -:: +.. code-block:: php + Doctrine 2 does not ship with any internal validators, the reason being that we think all the frameworks out there already ship with quite decent ones that can be integrated into your Domain easily. @@ -26,7 +28,7 @@ Say we have an ``Order`` with several ``OrderLine`` instances. We never want to allow any customer to order for a larger sum than he is allowed to: -:: +.. code-block:: php @@ -95,7 +96,7 @@ Of course you can do any type of primitive checks, not null, email-validation, string size, integer and date ranges in your validation callbacks. -:: +.. code-block:: php `_ - - +Further readings: :doc:`Lifecycle Events <../reference/events>` diff --git a/en/index.rst b/en/index.rst new file mode 100644 index 000000000..877bdc7c3 --- /dev/null +++ b/en/index.rst @@ -0,0 +1,70 @@ +Welcome to Doctrine 2 ORM's documentation! +========================================== + +Reference Guide +--------------- + +.. toctree:: + :maxdepth: 1 + :numbered: + + reference/introduction + reference/architecture + reference/configuration + reference/basic-mapping + reference/association-mapping + reference/inheritance-mapping + reference/working-with-objects + reference/working-with-associations + reference/transactions-and-concurrency + reference/events + reference/batch-processing + reference/dql-doctrine-query-language + reference/query-builder + reference/native-sql + reference/change-tracking-policies + reference/partial-objects + reference/xml-mapping + reference/yaml-mapping + reference/annotations-reference + reference/php-mapping + reference/caching + reference/improving-performance + reference/best-practices + reference/tools + reference/metadata-drivers + reference/best-practices + reference/limitations-and-known-issues + +Tutorials +--------- + +.. toctree:: + :maxdepth: 1 + + tutorials/getting-started-xml-edition + +Cookbook +-------- + +.. toctree:: + :maxdepth: 1 + + cookbook/aggregate-fields + cookbook/dql-custom-walkers + cookbook/dql-user-defined-functions + cookbook/implementing-arrayaccess-for-domain-objects + cookbook/implementing-the-notify-changetracking-policy + cookbook/implementing-wakeup-or-clone + cookbook/integrating-with-codeigniter + cookbook/sql-table-prefixes + cookbook/strategy-cookbook-introduction + cookbook/validation-of-entities + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/manual/en/make.bat b/en/make.bat similarity index 100% rename from manual/en/make.bat rename to en/make.bat diff --git a/manual/en/annotations-reference.rst b/en/reference/annotations-reference.rst similarity index 82% rename from manual/en/annotations-reference.rst rename to en/reference/annotations-reference.rst index 3b5cefddd..8795ed1a6 100644 --- a/manual/en/annotations-reference.rst +++ b/en/reference/annotations-reference.rst @@ -8,39 +8,41 @@ Index ----- -- `@Column <#ann_column>`_ -- `@ChangeTrackingPolicy <#ann_changetrackingpolicy>`_ -- `@DiscriminatorColumn <#ann_discriminatorcolumn>`_ -- `@DiscriminatorMap <#ann_discriminatormap>`_ -- `@Entity <#ann_entity>`_ -- `@GeneratedValue <#ann_generatedvalue>`_ -- `@HasLifecycleCallbacks <#ann_haslifecyclecallbacks>`_ -- `@Index <#ann_indexes>`_ -- `@Id <#ann_id>`_ -- `@InheritanceType <#ann_inheritancetype>`_ -- `@JoinColumn <#ann_joincolumn>`_ -- `@JoinTable <#ann_jointable>`_ -- `@ManyToOne <#ann_manytoone>`_ -- `@ManyToMany <#ann_manytomany>`_ -- `@MappedSuperclass <#ann_mappedsuperclass>`_ -- `@OneToOne <#ann_onetoone>`_ -- `@OneToMany <#ann_onetomany>`_ -- `@OrderBy <#ann_orderby>`_ -- `@PostLoad <#ann_postload>`_ -- `@PostPersist <#ann_postpersist>`_ -- `@PostRemove <#ann_postremove>`_ -- `@PostUpdate <#ann_postupdate>`_ -- `@PrePersist <#ann_prepersist>`_ -- `@PreRemove <#ann_preremove>`_ -- `@PreUpdate <#ann_preupdate>`_ -- `@SequenceGenerator <#ann_sequencegenerator>`_ -- `@Table <#ann_table>`_ -- `@UniqueConstraint <#ann_uniqueconstraint>`_ -- `@Version <#ann_version>`_ +- :ref:`@Column ` +- :ref:`@ChangeTrackingPolicy ` +- :ref:`@DiscriminatorColumn ` +- :ref:`@DiscriminatorMap ` +- :ref:`@Entity ` +- :ref:`@GeneratedValue ` +- :ref:`@HasLifecycleCallbacks ` +- :ref:`@Index ` +- :ref:`@Id ` +- :ref:`@InheritanceType ` +- :ref:`@JoinColumn ` +- :ref:`@JoinTable ` +- :ref:`@ManyToOne ` +- :ref:`@ManyToMany ` +- :ref:`@MappedSuperclass ` +- :ref:`@OneToOne ` +- :ref:`@OneToMany ` +- :ref:`@OrderBy ` +- :ref:`@PostLoad ` +- :ref:`@PostPersist ` +- :ref:`@PostRemove ` +- :ref:`@PostUpdate ` +- :ref:`@PrePersist ` +- :ref:`@PreRemove ` +- :ref:`@PreUpdate ` +- :ref:`@SequenceGenerator ` +- :ref:`@Table ` +- :ref:`@UniqueConstraint ` +- :ref:`@Version ` Reference --------- +.. _annref_column: + @Column ~~~~~~~ @@ -79,11 +81,11 @@ Optional attributes: 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>`_. + :ref:`@JoinColumn `. Examples: -:: +.. code-block:: php `_ +The :doc:`details on all the available change tracking policies ` can be found in the configuration section. Example: -:: +.. code-block:: php `_. This +instance variable which is annotated by :ref:`@Id `. This annotation is optional and only has meaning when used in conjunction with @Id. @@ -220,7 +231,7 @@ Required attributes: Example: -:: +.. code-block:: php `_ annotation on +Annotation is used inside the :ref:`@Table ` annotation on the entity-class level. It allows to hint the SchemaTool to generate a database index on the specified table columns. It only has meaning in the SchemaTool schema generation context. @@ -273,7 +288,7 @@ Required attributes: Example: -:: +.. code-block:: php `_ and -`@DiscriminatorColumn <#ann_discriminatorcolumn>`_ annotations. +:ref:`@DiscriminatorMap ` and +:ref:`@DiscriminatorColumn ` annotations. Examples: -:: +.. code-block:: php `_, `@OneToOne <#ann_onetoone>`_ fields -and in the Context of `@JoinTable <#ann_jointable>`_ nested inside +:ref:`@ManyToOne `, :ref:`@OneToOne ` fields +and in the Context of :ref:`@JoinTable ` nested inside a @ManyToMany. This annotation is not required. If its not specified the attributes *name* and *referencedColumnName* are inferred from the table and primary key names. @@ -378,13 +399,13 @@ Optional attributes: 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 + "columnDefinition" attribute on :ref:`@Column ` also sets the related @JoinColumn's columnDefinition. This is necessary to make foreign keys work. Example: -:: +.. code-block:: php `_ or `@OneToOne <#ann_onetoone>`_ +:ref:`@ManyToOne ` or :ref:`@OneToOne ` relation with an entity that has multiple identifiers. +.. _annref_jointable: + @JoinTable ~~~~~~~~~~~~~~ -Using `@OneToMany <#ann_onetomany>`_ or -`@ManyToMany <#ann_manytomany>`_ on the owning side of the relation +Using :ref:`@OneToMany ` or +:ref:`@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 @@ -427,7 +452,7 @@ Optional attributes: Example: -:: +.. code-block:: php `_ is an +between two entities. :ref:`@JoinTable ` is an additional, optional annotation that has reasonable default configuration values using the table and names of the two related entities. @@ -505,7 +534,7 @@ Optional attributes: Example: -:: +.. code-block:: php `_. +:doc:`more details on the restrictions of mapped superclasses `. + +.. _annref_onetoone: @OneToOne ~~~~~~~~~~~~~~ The @OneToOne annotation works almost exactly as the -`@ManyToOne <#ann_manytoone>`_ with one additional option that can +:ref:`@ManyToOne ` with one additional option that can be specified. The configuration defaults for -`@JoinColumn <#ann_joincolumn>`_ using the target entity table and +:ref:`@JoinColumn ` using the target entity table and primary key column names apply here too. Required attributes: @@ -567,7 +600,7 @@ Optional attributes: Example: -:: +.. code-block:: php `_ or `@OneToMany <#ann_onetomany>`_ +:ref:`@ManyToMany ` or :ref:`@OneToMany ` annotation to specify by which criteria the collection should be retrieved from the database by using an ORDER BY clause. @@ -620,7 +657,7 @@ snippet: Example: -:: +.. code-block:: php `_ annotation on +Annotation is used inside the :ref:`@Table ` annotation on the entity-class level. It allows to hint the SchemaTool to generate a database unique constraint on the specified table columns. It only has meaning in the SchemaTool schema generation @@ -769,7 +826,7 @@ Required attributes: Example: -:: +.. code-block:: php `_ annotations that have the type integer or -datetime. +:ref:`@Column ` annotations that have the type integer or +datetime. Combining @Version with :ref:`@Id ` is not supported. Example: -:: +.. code-block:: php find('Group', $groupId); @@ -266,13 +268,13 @@ associations are correctly defined. You can either use the Doctrine Command Line Tool: -:: +.. code-block:: php doctrine orm:validate-schema Or you can trigger the validation manually: -:: +.. code-block:: php use Doctrine\ORM\Tools\SchemaValidator; @@ -304,7 +306,7 @@ example of a ``Product`` that has one ``Shipping`` object associated to it. The ``Shipping`` side does not reference back to the ``Product`` so it is unidirectional. -:: +.. code-block:: php 10 However the following: diff --git a/manual/en/basic-mapping.rst b/en/reference/basic-mapping.rst similarity index 96% rename from manual/en/basic-mapping.rst rename to en/reference/basic-mapping.rst index 506337092..95a1d8c4d 100644 --- a/manual/en/basic-mapping.rst +++ b/en/reference/basic-mapping.rst @@ -23,7 +23,8 @@ chapters for XML and YAML mapping, respectively. .. note:: If you're wondering which mapping driver gives the best - performance, the answer is: None. Once the metadata of a class has + performance, the answer is: They all give exactly the same performance. + Once the metadata of a class has been read from the source (annotations, xml or yaml) it is stored in an instance of the ``Doctrine\ORM\Mapping\ClassMetadata`` class and these instances are stored in the metadata cache. Therefore at @@ -68,7 +69,7 @@ In order to mark a class for object-relational persistence it needs to be designated as an entity. This can be done through the ``@Entity`` marker annotation. -:: +.. code-block:: php getConnection(); @@ -327,7 +324,7 @@ Every entity class needs an identifier/primary key. You designate the field that serves as the identifier with the ``@Id`` marker annotation. Here is an example: -:: +.. code-block:: php createQuery('update MyProject\Model\Manager m set m.salary = m.salary * 0.9'); @@ -69,7 +69,7 @@ by step instead of loading the whole result into memory at once. The following example shows how to do this, combining the iteration with the batching strategy that was already used for bulk inserts: -:: +.. code-block:: php createQuery('delete from MyProject\Model\Manager m where m.salary > 100000'); @@ -121,7 +123,7 @@ An alternative solution for bulk deletes is to use the by step instead of loading the whole result into memory at once. The following example shows how to do this: -:: +.. code-block:: php iterate()`` implements the Iterator interface so you can process a large result without memory problems using the following approach: -:: +.. code-block:: php _em->createQuery('select u from MyProject\Model\User u'); @@ -163,7 +167,9 @@ problems using the following approach: $this->_em->detach($row[0]); } - **NOTE** Iterating results is not possible with queries that +.. note:: + + Iterating results is not possible with queries that fetch-join a collection-valued association. The nature of such SQL result sets is not suitable for incremental hydration. diff --git a/manual/en/best-practices.rst b/en/reference/best-practices.rst similarity index 99% rename from manual/en/best-practices.rst rename to en/reference/best-practices.rst index 28709666f..f58291d18 100644 --- a/manual/en/best-practices.rst +++ b/en/reference/best-practices.rst @@ -85,7 +85,7 @@ Initialize collections in the constructor It is recommended best practice to initialize any business collections in entities in the constructor. Example: -:: +.. code-block:: php `_ on the PHP website. It will give +`in the PHP Documentation `_. It will give you a little background information about what it is and how you can use it as well as how to install it. Below is a simple example of how you could use the APC cache driver by itself. -:: +.. code-block:: php `_ on the PHP website. It will +` on the PHP website `_. It will give you a little background information about what it is and how you can use it as well as how to install it. Below is a simple example of how you could use the Memcache cache driver by itself. -:: +.. code-block:: php save('cache_id', 'my_data'); @@ -136,7 +136,7 @@ below. You can save any type of data whether it be a string, array, object, etc. -:: +.. code-block:: php contains('cache_id')) { @@ -168,7 +168,7 @@ Now if you want to retrieve some cache entry you can use the ``fetch()`` method. It also accepts a single argument just like ``contains()`` which is the ID of the cache entry. -:: +.. code-block:: php fetch('my_array'); @@ -184,7 +184,7 @@ you can delete all entries. By Cache ID ^^^^^^^^^^^ -:: +.. code-block:: php delete('my_array'); @@ -192,7 +192,7 @@ By Cache ID You can also pass wild cards to the ``delete()`` method and it will return an array of IDs that were matched and deleted. -:: +.. code-block:: php delete('users_*'); @@ -203,7 +203,7 @@ By Regular Expression If you need a little more control than wild cards you can use a PHP regular expression to delete cache entries. -:: +.. code-block:: php deleteByRegex('/users_.*/'); @@ -216,7 +216,7 @@ a prefix or suffix is sufficient, it is recommended that you do that instead of using a regular expression because it will be much faster if you have many cache entries. -:: +.. code-block:: php deleteByPrefix('users_'); @@ -227,7 +227,7 @@ By Suffix Just like we did above with the prefix you can do the same with a suffix. -:: +.. code-block:: php deleteBySuffix('_my_account'); @@ -238,7 +238,7 @@ All If you simply want to delete all cache entries you can do so with the ``deleteAll()`` method. -:: +.. code-block:: php deleteAll(); @@ -249,12 +249,14 @@ Counting If you want to count how many entries are stored in the cache driver instance you can use the ``count()`` method. -:: +.. code-block:: php count(); - **NOTE** In order to use ``deleteByRegex()``, ``deleteByPrefix()``, +.. note:: + + In order to use ``deleteByRegex()``, ``deleteByPrefix()``, ``deleteBySuffix()``, ``deleteAll()``, ``count()`` or ``getIds()`` you must enable an option for the cache driver to manage your cache IDs internally. This is necessary because APC, Memcache, etc. don't @@ -279,7 +281,7 @@ naming collisions. This can be worked around by using namespaces. You can set the namespace a cache driver should use by using the ``setNamespace()`` method. -:: +.. code-block:: php setNamespace('my_namespace_'); @@ -303,7 +305,7 @@ change unless you alter the DQL query. This can be done by configuring the query cache implementation to use on your ORM configuration. -:: +.. code-block:: php setResultCacheImpl(new \Doctrine\Common\Cache\ApcCache()); @@ -325,7 +327,7 @@ cache implementation. Now when you're executing DQL queries you can configure them to use the result cache. -:: +.. code-block:: php createQuery('select u from \Entities\User u'); @@ -334,12 +336,14 @@ the result cache. You can also configure an individual query to use a different result cache driver. -:: +.. code-block:: php setResultCacheDriver(new \Doctrine\Common\Cache\ApcCache()); - **NOTE** Setting the result cache driver on the query will +.. note:: + + Setting the result cache driver on the query will automatically enable the result cache for the query. If you want to disable it pass false to ``useResultCache()``. @@ -352,7 +356,7 @@ result cache driver. If you want to set the time the cache has to live you can use the ``setResultCacheLifetime()`` method. -:: +.. code-block:: php setResultCacheLifetime(3600); @@ -361,7 +365,7 @@ The ID used to store the result set cache is a hash which is automatically generated for you if you don't set a custom ID yourself with the ``setResultCacheId()`` method. -:: +.. code-block:: php setResultCacheId('my_custom_id'); @@ -369,7 +373,7 @@ yourself with the ``setResultCacheId()`` method. You can also set the lifetime and cache ID by passing the values as the second and third argument to ``useResultCache()``. -:: +.. code-block:: php useResultCache(true, 3600, 'my_custom_id'); @@ -384,7 +388,7 @@ each request we should cache it using one of the cache drivers. Just like the query and result cache we need to configure it first. -:: +.. code-block:: php setMetadataCacheImpl(new \Doctrine\Common\Cache\ApcCache()); @@ -402,7 +406,7 @@ clearing the query, result and metadata cache. From the Doctrine command line you can run the following command. -:: +.. code-block:: php $ ./doctrine clear-cache @@ -412,19 +416,19 @@ what you clear you can use the following options. To clear the query cache use the ``--query`` option. -:: +.. code-block:: php $ ./doctrine clear-cache --query To clear the metadata cache use the ``--metadata`` option. -:: +.. code-block:: php $ ./doctrine clear-cache --metadata To clear the result cache use the ``--result`` option. -:: +.. code-block:: php $ ./doctrine clear-cache --result @@ -435,29 +439,31 @@ clear. Just like the API of the cache drivers you can clear based on an ID, regular expression, prefix or suffix. -:: +.. code-block:: php $ ./doctrine clear-cache --result --id=cache_id Or if you want to clear based on a regular expressions. -:: +.. code-block:: php $ ./doctrine clear-cache --result --regex=users_.* Or with a prefix. -:: +.. code-block:: php $ ./doctrine clear-cache --result --prefix=users_ And finally with a suffix. -:: +.. code-block:: php $ ./doctrine clear-cache --result --suffix=_my_account - **NOTE** Using the ``--id``, ``--regex``, etc. options with the +.. note:: + + Using the ``--id``, ``--regex``, etc. options with the ``--query`` and ``--metadata`` are not allowed as it is not necessary to be specific about what you clear. You only ever need to completely clear the cache to remove stale entries. @@ -477,6 +483,6 @@ Ways exist to work around this, like pre-populating your cache and not letting your users requests populate the cache. You can read more about cache slams -`here `_. +`in this blog post `_. diff --git a/manual/en/change-tracking-policies.rst b/en/reference/change-tracking-policies.rst similarity index 98% rename from manual/en/change-tracking-policies.rst rename to en/reference/change-tracking-policies.rst index 25f32d051..7bd884910 100644 --- a/manual/en/change-tracking-policies.rst +++ b/en/reference/change-tracking-policies.rst @@ -46,7 +46,7 @@ them to EntityManager#persist(). This policy can be configured as follows: -:: +.. code-block:: php setProxyDir($dir); @@ -181,7 +185,7 @@ down. Proxy Namespace (***REQUIRED***) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:: +.. code-block:: php setProxyNamespace($namespace); @@ -194,7 +198,7 @@ Doctrine, refer to the "Proxy Objects" section further down. Metadata Driver (***REQUIRED***) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:: +.. code-block:: php setMetadataDriverImpl($driver); @@ -220,7 +224,7 @@ or YamlDriver please refer to the dedicated chapters The annotation driver can be configured with a factory method on the ``Doctrine\ORM\Configuration``: -:: +.. code-block:: php newDefaultAnnotationDriver('/path/to/lib/MyProject/Entities'); @@ -236,7 +240,7 @@ directories of Entities. Metadata Cache (***RECOMMENDED***) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:: +.. code-block:: php setMetadataCacheImpl($cache); @@ -265,7 +269,7 @@ per-request basis. Query Cache (***RECOMMENDED***) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:: +.. code-block:: php setQueryCacheImpl($cache); @@ -295,7 +299,7 @@ per-request basis. SQL Logger (***Optional***) ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:: +.. code-block:: php setSQLLogger($logger); @@ -311,7 +315,7 @@ implementation that logs to the standard output using ``echo`` and Auto-generating Proxy Classes (***OPTIONAL***) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:: +.. code-block:: php setAutoGenerateProxyClasses($bool); @@ -385,7 +389,7 @@ useful, for example, as a performance enhancement, when you want to establish an association to an entity for which you have the identifier. You could simply do this: -:: +.. code-block:: php setAutoGenerateProxyClasses($bool); @@ -444,7 +448,7 @@ added to the entity class that are not yet in the proxy class. In such a case, simply use the Doctrine Console to (re)generate the proxy classes like so: -:: +.. code-block:: php $ ./doctrine orm:generate-proxies @@ -456,7 +460,7 @@ with them using two different metadata drivers, for example XML and YAML. You can use the DriverChain Metadata implementations to aggregate these drivers based on namespaces: -:: +.. code-block:: php 20: -:: +.. code-block:: php createQuery('SELECT u FROM MyProject\Model\User u WHERE u.age > 20'); @@ -115,7 +116,7 @@ Example: Regular join of the address: -:: +.. code-block:: php createQuery("SELECT u FROM User u JOIN u.address a WHERE a.city = 'Berlin'"); @@ -123,7 +124,7 @@ Regular join of the address: Fetch join of the address: -:: +.. code-block:: php createQuery("SELECT u, a FROM User u JOIN u.address a WHERE a.city = 'Berlin'"); @@ -165,7 +166,7 @@ on the hydration mode. Hydrate all User entities: -:: +.. code-block:: php createQuery('SELECT u FROM MyProject\Model\User u'); @@ -173,7 +174,7 @@ Hydrate all User entities: Retrieve the IDs of all CmsUsers: -:: +.. code-block:: php createQuery('SELECT u.id FROM CmsUser u'); @@ -181,7 +182,7 @@ Retrieve the IDs of all CmsUsers: Retrieve the IDs of all users that have written an article: -:: +.. code-block:: php createQuery('SELECT DISTINCT u.id FROM CmsArticle a JOIN a.user u'); @@ -190,7 +191,7 @@ Retrieve the IDs of all users that have written an article: Retrieve all articles and sort them by the name of the articles users instance: -:: +.. code-block:: php createQuery('SELECT a FROM CmsArticle a JOIN a.user u ORDER BY u.name ASC'); @@ -198,7 +199,7 @@ users instance: Retrieve the Username and Name of a CmsUser: -:: +.. code-block:: php createQuery('SELECT u.username, u.name FROM CmsUser u'); @@ -207,7 +208,7 @@ Retrieve the Username and Name of a CmsUser: Retrieve a ForumUser and his single associated entity: -:: +.. code-block:: php createQuery('SELECT u, a FROM ForumUser u JOIN u.avatar a'); @@ -216,7 +217,7 @@ Retrieve a ForumUser and his single associated entity: Retrieve a CmsUser and fetch join all the phonenumbers he has: -:: +.. code-block:: php createQuery('SELECT u, p FROM CmsUser u JOIN u.phonenumbers p'); @@ -225,7 +226,7 @@ Retrieve a CmsUser and fetch join all the phonenumbers he has: Hydrate a result in Ascending: -:: +.. code-block:: php createQuery('SELECT u FROM ForumUser u ORDER BY u.id ASC'); @@ -233,7 +234,7 @@ Hydrate a result in Ascending: Or in Descending Order: -:: +.. code-block:: php createQuery('SELECT u FROM ForumUser u ORDER BY u.id DESC'); @@ -241,7 +242,7 @@ Or in Descending Order: Using Aggregate Functions: -:: +.. code-block:: php createQuery('SELECT COUNT(u.id) FROM Entities\User u'); @@ -249,7 +250,7 @@ Using Aggregate Functions: With WHERE Clause and Positional Parameter: -:: +.. code-block:: php createQuery('SELECT u FROM ForumUser u WHERE u.id = ?1'); @@ -257,7 +258,7 @@ With WHERE Clause and Positional Parameter: With WHERE Clause and Named Parameter: -:: +.. code-block:: php createQuery('SELECT u FROM ForumUser u WHERE u.username = :name'); @@ -265,7 +266,7 @@ With WHERE Clause and Named Parameter: With Nested Conditions in WHERE Clause: -:: +.. code-block:: php createQuery('SELECT u from ForumUser u WHERE (u.username = :name OR u.username = :name2) AND u.id = :id'); @@ -273,7 +274,7 @@ With Nested Conditions in WHERE Clause: With COUNT DISTINCT: -:: +.. code-block:: php createQuery('SELECT COUNT(DISTINCT u.name) FROM CmsUser'); @@ -281,7 +282,7 @@ With COUNT DISTINCT: With Arithmetic Expression in WHERE clause: -:: +.. code-block:: php createQuery('SELECT u FROM CmsUser u WHERE ((u.id + 5000) * u.id + 3) < 10000000'); @@ -290,7 +291,7 @@ With Arithmetic Expression in WHERE clause: Using a LEFT JOIN to hydrate all user-ids and optionally associated article-ids: -:: +.. code-block:: php createQuery('SELECT u.id, a.id as article_id FROM CmsUser u LEFT JOIN u.articles a'); @@ -298,7 +299,7 @@ article-ids: Restricting a JOIN clause by additional conditions: -:: +.. code-block:: php createQuery("SELECT u FROM CmsUser u LEFT JOIN u.articles a WITH a.topic LIKE '%foo%'"); @@ -306,7 +307,7 @@ Restricting a JOIN clause by additional conditions: Using several Fetch JOINs: -:: +.. code-block:: php createQuery('SELECT u, a, p, c FROM CmsUser u JOIN u.articles a JOIN u.phonenumbers p JOIN a.comments c'); @@ -314,7 +315,7 @@ Using several Fetch JOINs: BETWEEN in WHERE clause: -:: +.. code-block:: php createQuery('SELECT u.name FROM CmsUser u WHERE u.id BETWEEN ?1 AND ?2'); @@ -322,7 +323,7 @@ BETWEEN in WHERE clause: DQL Functions in WHERE clause: -:: +.. code-block:: php createQuery("SELECT u.name FROM CmsUser u WHERE TRIM(u.name) = 'someone'"); @@ -330,7 +331,7 @@ DQL Functions in WHERE clause: IN() Expression: -:: +.. code-block:: php createQuery('SELECT u.name FROM CmsUser u WHERE u.id IN(46)'); @@ -344,7 +345,7 @@ IN() Expression: CONCAT() DQL Function: -:: +.. code-block:: php createQuery("SELECT u.id FROM CmsUser u WHERE CONCAT(u.name, 's') = ?1"); @@ -355,7 +356,7 @@ CONCAT() DQL Function: EXISTS in WHERE clause with correlated Subquery -:: +.. code-block:: php createQuery('SELECT u.id FROM CmsUser u WHERE EXISTS (SELECT p.phonenumber FROM CmsPhonenumber p WHERE p.user = u.id)'); @@ -363,7 +364,7 @@ EXISTS in WHERE clause with correlated Subquery Get all users who are members of $group. -:: +.. code-block:: php createQuery('SELECT u.id FROM CmsUser u WHERE :groupId MEMBER OF u.groups'); @@ -372,7 +373,7 @@ Get all users who are members of $group. Get all users that have more than 1 phonenumber -:: +.. code-block:: php createQuery('SELECT u FROM CmsUser u WHERE SIZE(u.phonenumbers) > 1'); @@ -380,7 +381,7 @@ Get all users that have more than 1 phonenumber Get all users that have no phonenumber -:: +.. code-block:: php createQuery('SELECT u FROM CmsUser u WHERE u.phonenumbers IS EMPTY'); @@ -389,7 +390,7 @@ Get all users that have no phonenumber Get all instances of a specific type, for use with inheritance hierarchies: -:: +.. code-block:: php createQuery('SELECT u FROM Doctrine\Tests\Models\Company\CompanyPerson u WHERE u INSTANCE OF Doctrine\Tests\Models\Company\CompanyEmployee'); @@ -408,7 +409,7 @@ and joining some data. If you want to select partial objects you can use the ``partial`` DQL keyword: -:: +.. code-block:: php createQuery('SELECT partial u.{id, username} FROM CmsUser u'); @@ -416,7 +417,7 @@ DQL keyword: You use the partial syntax when joining as well: -:: +.. code-block:: php createQuery('SELECT partial u.{id, username}, partial a.{id, name} FROM CmsUser u JOIN u.articles a'); @@ -441,7 +442,7 @@ with primary or unique fields though: Returns an array of the following kind, indexed by both user-id then phonenumber-id: -:: +.. code-block:: php array 0 => @@ -543,7 +544,7 @@ Arithmetic operators You can do math in DQL using numeric values, for example: -.. warning:: +.. code-block:: sql SELECT person.salary * 1.5 FROM CompanyPerson person WHERE person.salary < 100000 @@ -582,7 +583,7 @@ parser with own specialized platform functions. You can register custom DQL functions in your ORM Configuration: -:: +.. code-block:: php Object @@ -873,7 +876,7 @@ A pure result usually looks like this: A mixed result on the other hand has the following general structure: -:: +.. code-block:: php array array @@ -900,7 +903,7 @@ clause, we get a mixed result. Here is how the result could look like: -:: +.. code-block:: php array array @@ -913,7 +916,7 @@ Here is how the result could look like: And here is how you would access it in PHP code: -:: +.. code-block:: php createQuery('SELECT u FROM CmsUser u'); @@ -956,7 +959,7 @@ Array Hydration You can run the same query with array hydration and the result set is hydrated into an array that represents the object graph: -:: +.. code-block:: php createQuery('SELECT u FROM CmsUser u'); @@ -964,7 +967,7 @@ is hydrated into an array that represents the object graph: You can use the ``getArrayResult()`` shortcut as well: -:: +.. code-block:: php getArrayResult(); @@ -975,7 +978,7 @@ Scalar Hydration If you want to return a flat rectangular result set instead of an object graph you can use scalar hydration: -:: +.. code-block:: php createQuery('SELECT u FROM CmsUser u'); @@ -996,7 +999,7 @@ Single Scalar Hydration If you a query which returns just a single scalar value you can use single scalar hydration: -:: +.. code-block:: php createQuery('SELECT COUNT(a.id) FROM CmsUser u LEFT JOIN u.articles a WHERE u.username = ?1 GROUP BY u.id'); @@ -1005,7 +1008,7 @@ single scalar hydration: You can use the ``getSingleScalarResult()`` shortcut as well: -:: +.. code-block:: php getSingleScalarResult(); @@ -1016,7 +1019,7 @@ Custom Hydration Modes You can easily add your own custom hydration modes by first creating a class which extends ``AbstractHydrator``: -:: +.. code-block:: php getConfiguration()->addCustomHydrationMode('CustomHydrator', 'MyProject\Hydrators\CustomHydrator'); Now the hydrator is ready to be used in your queries: -:: +.. code-block:: php createQuery('SELECT u FROM CmsUser u'); @@ -1087,7 +1090,7 @@ cached at all. You have to enable the result cache on a per query basis. The following example shows a complete workflow using the Result Cache API: -:: +.. code-block:: php createQuery('SELECT u FROM MyProject\Model\User u WHERE u.id = ?1'); @@ -1229,14 +1232,14 @@ Terminals Query Language ~~~~~~~~~~~~~~ -:: +.. code-block:: php QueryLanguage ::= SelectStatement | UpdateStatement | DeleteStatement Statements ~~~~~~~~~~ -:: +.. code-block:: php SelectStatement ::= SelectClause FromClause [WhereClause] [GroupByClause] [HavingClause] [OrderByClause] UpdateStatement ::= UpdateClause [WhereClause] @@ -1245,7 +1248,7 @@ Statements Identifiers ~~~~~~~~~~~ -:: +.. code-block:: php /* Alias Identification usage (the "u" of "u.name") */ IdentificationVariable ::= identifier @@ -1282,7 +1285,7 @@ Identifiers Path Expressions ~~~~~~~~~~~~~~~~ -:: +.. code-block:: php /* "u.Group" or "u.Phonenumbers" declarations */ JoinAssociationPathExpression ::= IdentificationVariable "." (CollectionValuedAssociationField | SingleValuedAssociationField) @@ -1311,7 +1314,7 @@ Path Expressions Clauses ~~~~~~~ -:: +.. code-block:: php SelectClause ::= "SELECT" ["DISTINCT"] SelectExpression {"," SelectExpression}* SimpleSelectClause ::= "SELECT" ["DISTINCT"] SimpleSelectExpression @@ -1328,7 +1331,7 @@ Clauses Items ~~~~~ -:: +.. code-block:: php UpdateItem ::= IdentificationVariable "." (StateField | SingleValuedAssociationField) "=" NewValue OrderByItem ::= (ResultVariable | StateFieldPathExpression) ["ASC" | "DESC"] @@ -1338,7 +1341,7 @@ Items From, Join and Index by ~~~~~~~~~~~~~~~~~~~~~~~ -:: +.. code-block:: php IdentificationVariableDeclaration ::= RangeVariableDeclaration [IndexBy] {JoinVariableDeclaration}* SubselectIdentificationVariableDeclaration ::= IdentificationVariableDeclaration | (AssociationPathExpression ["AS"] AliasIdentificationVariable) @@ -1351,7 +1354,7 @@ From, Join and Index by Select Expressions ~~~~~~~~~~~~~~~~~~ -:: +.. code-block:: php SelectExpression ::= IdentificationVariable | PartialObjectExpression | (AggregateExpression | "(" Subselect ")" | FunctionDeclaration | ScalarExpression) [["AS"] AliasResultVariable] SimpleSelectExpression ::= ScalarExpression | IdentificationVariable | @@ -1362,7 +1365,7 @@ Select Expressions Conditional Expressions ~~~~~~~~~~~~~~~~~~~~~~~ -:: +.. code-block:: php ConditionalExpression ::= ConditionalTerm {"OR" ConditionalTerm}* ConditionalTerm ::= ConditionalFactor {"AND" ConditionalFactor}* @@ -1375,7 +1378,7 @@ Conditional Expressions Collection Expressions ~~~~~~~~~~~~~~~~~~~~~~ -:: +.. code-block:: php EmptyCollectionComparisonExpression ::= CollectionValuedPathExpression "IS" ["NOT"] "EMPTY" CollectionMemberExpression ::= EntityExpression ["NOT"] "MEMBER" ["OF"] CollectionValuedPathExpression @@ -1383,7 +1386,7 @@ Collection Expressions Literal Values ~~~~~~~~~~~~~~ -:: +.. code-block:: php Literal ::= string | char | integer | float | boolean InParameter ::= Literal | InputParameter @@ -1391,7 +1394,7 @@ Literal Values Input Parameter ~~~~~~~~~~~~~~~ -:: +.. code-block:: php InputParameter ::= PositionalParameter | NamedParameter PositionalParameter ::= "?" integer @@ -1400,7 +1403,7 @@ Input Parameter Arithmetic Expressions ~~~~~~~~~~~~~~~~~~~~~~ -:: +.. code-block:: php ArithmeticExpression ::= SimpleArithmeticExpression | "(" Subselect ")" SimpleArithmeticExpression ::= ArithmeticTerm {("+" | "-") ArithmeticTerm}* @@ -1413,7 +1416,7 @@ Arithmetic Expressions Scalar and Type Expressions ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:: +.. code-block:: php ScalarExpression ::= SimpleArithmeticExpression | StringPrimary | DateTimePrimary | StateFieldPathExpression BooleanPrimary | CaseExpression | EntityTypeExpression @@ -1440,7 +1443,7 @@ Scalar and Type Expressions Aggregate Expressions ~~~~~~~~~~~~~~~~~~~~~ -:: +.. code-block:: php AggregateExpression ::= ("AVG" | "MAX" | "MIN" | "SUM") "(" ["DISTINCT"] StateFieldPathExpression ")" | "COUNT" "(" ["DISTINCT"] (IdentificationVariable | SingleValuedPathExpression) ")" @@ -1450,7 +1453,7 @@ Other Expressions QUANTIFIED/BETWEEN/COMPARISON/LIKE/NULL/EXISTS -:: +.. code-block:: php QuantifiedExpression ::= ("ALL" | "ANY" | "SOME") "(" Subselect ")" BetweenExpression ::= ArithmeticExpression ["NOT"] "BETWEEN" ArithmeticExpression "AND" ArithmeticExpression @@ -1464,7 +1467,7 @@ QUANTIFIED/BETWEEN/COMPARISON/LIKE/NULL/EXISTS Functions ~~~~~~~~~ -:: +.. code-block:: php FunctionDeclaration ::= FunctionsReturningStrings | FunctionsReturningNumerics | FunctionsReturningDateTime diff --git a/manual/en/events.rst b/en/reference/events.rst similarity index 98% rename from manual/en/events.rst rename to en/reference/events.rst index ebdeee81b..836980d41 100644 --- a/manual/en/events.rst +++ b/en/reference/events.rst @@ -12,7 +12,7 @@ central point of Doctrine's event listener system. Listeners are registered on the manager and events are dispatched through the manager. -:: +.. code-block:: php dispatchEvent(EventTest::preFoo); @@ -63,7 +63,7 @@ Events can be dispatched by using the ``dispatchEvent()`` method. You can easily remove a listener with the ``removeEventListener()`` method. -:: +.. code-block:: php removeEventListener(array(self::preFoo, self::postFoo), $this); @@ -74,7 +74,7 @@ which implements the ``\Doctrine\Common\EventSubscriber`` interface and implements a ``getSubscribedEvents()`` method which returns an array of events it should be subscribed to. -:: +.. code-block:: php dispatchEvent(TestEvent::preFoo); @@ -106,7 +106,7 @@ notified for that event. Now you can test the ``$eventSubscriber`` instance to see if the ``preFoo()`` method was invoked. -:: +.. code-block:: php preFooInvoked) { @@ -178,7 +178,7 @@ the life-time of their registered entities. You can access the Event constants from the ``Events`` class in the ORM package. -:: +.. code-block:: php getEventManager()->addEventListener(array(Events::preUpdate), MyEventListener()); @@ -436,7 +434,7 @@ To make use of the onFlush event you have to be familiar with the internal UnitOfWork API, which grants you access to the previously mentioned sets. See this example: -:: +.. code-block:: php If you want to use the Doctrine Database Abstraction Layer you can install it with the following command. -:: +.. code-block:: bash $ sudo pear install pear.doctrine-project.org/DoctrineDBAL- Or, if you want to get the works and go for the ORM you can install it with the following command. -:: +.. code-block:: bash $ sudo pear install pear.doctrine-project.org/DoctrineORM- @@ -122,7 +122,7 @@ it with the following command. writing this is ``2.0.0BETA3`` for the ORM, so you could install it like the following: - :: + .. code-block:: bash $ sudo pear install pear.doctrine-project.org/DoctrineORM-2.0.0BETA3 @@ -130,7 +130,7 @@ it with the following command. When you have a package installed via PEAR you can require and load the ``ClassLoader`` with the following code. -:: +.. code-block:: php @@ -394,11 +394,8 @@ Can you **find** the easier way?). 6) Explore Doctrine 2! -See the following links if you want to start with more complex -tutorials rather than reading the manual: - - -- Doctrine2 Cookbook: - `Getting Started XML Edition `_ +Instead of reading through the reference manual we also recommend to look at the tutorials: + +:doc:`Getting Started XML Edition <../tutorials/getting-started-xml-edition>` diff --git a/manual/en/limitations-and-known-issues.rst b/en/reference/limitations-and-known-issues.rst similarity index 99% rename from manual/en/limitations-and-known-issues.rst rename to en/reference/limitations-and-known-issues.rst index 8631c2d7d..dbf5cd7e5 100644 --- a/manual/en/limitations-and-known-issues.rst +++ b/en/reference/limitations-and-known-issues.rst @@ -60,7 +60,7 @@ the fundamental difference between the two different ``product_attributes`` tables you should see how they translate into a Doctrine Mapping (Using Annotations): -:: +.. code-block:: php getConfiguration()->setMetadataCacheImpl(new ApcCache()); @@ -40,7 +42,7 @@ If you want to use one of the included core metadata drivers you just need to configure it. All the drivers are in the ``Doctrine\ORM\Mapping\Driver`` namespace: -:: +.. code-block:: php getMetadataFactory(); @@ -180,7 +184,7 @@ Now you can learn about the entity and use the data stored in the ``ClassMetadata`` instance to get all mapped fields for example and iterate over them: -:: +.. code-block:: php fieldMappings as $fieldMapping) { diff --git a/manual/en/native-sql.rst b/en/reference/native-sql.rst similarity index 98% rename from manual/en/native-sql.rst rename to en/reference/native-sql.rst index 992eefc06..77bd0ad78 100644 --- a/manual/en/native-sql.rst +++ b/en/reference/native-sql.rst @@ -67,7 +67,7 @@ element in the transformed result. You add an entity result through ``ResultSetMapping#addEntityResult()``. Let's take a look at the method signature in detail: -:: +.. code-block:: php User (Object) @@ -269,7 +269,7 @@ assumes User has a unidirectional or bidirectional one-to-one association to a CmsAddress, where the User is the owning side and thus owns the foreign key. -:: +.. code-block:: php createQuery("select partial u.{id,name} from MyApp\Domain\User u"); diff --git a/manual/en/php-mapping.rst b/en/reference/php-mapping.rst similarity index 95% rename from manual/en/php-mapping.rst rename to en/reference/php-mapping.rst index 21fb33fec..6ba0755c3 100644 --- a/manual/en/php-mapping.rst +++ b/en/reference/php-mapping.rst @@ -13,7 +13,7 @@ If you wish to write your mapping information inside PHP files that are named after the entity and included to populate the metadata for an entity you can do so by using the ``PHPDriver``: -:: +.. code-block:: php getMetadataFor('Entities\User'); + $class = $em->getClassMetadata('Entities\User'); + // or + $class = $em->getMetadataFactory()->getMetadataFor('Entities\User'); Static Function --------------- @@ -72,7 +74,7 @@ itself. This is useful for cases where you want to keep your entity and mapping information together but don't want to use annotations. For this you just need to use the ``StaticPHPDriver``: -:: +.. code-block:: php expr()->*`` methods. Here is a converted example 8 to suggested standard way to build queries: -:: +.. code-block:: php addCommand(new \MyProject\Tools\Console\Commands\MyCustomCommand()); @@ -119,7 +119,7 @@ do: Additionally, include multiple commands (and overriding previously defined ones) is possible through the command: -:: +.. code-block:: php addCommands(array( @@ -200,7 +200,7 @@ the ``createSchema()`` method. First create an instance of the that you want to use to create the schema. This method receives an array of ``ClassMetadataInfo`` instances. -:: +.. code-block:: php dropSchema($classes); @@ -222,7 +222,7 @@ model. 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. -:: +.. code-block:: php dropSchema($classes, \Doctrine\ORM\Tools\SchemaTool::DROP_DATABASE); @@ -232,7 +232,7 @@ easily with the ``updateSchema()`` method. It will compare your existing database schema to the passed array of ``ClassMetdataInfo`` instances. -:: +.. code-block:: php updateSchema($classes); @@ -242,20 +242,20 @@ use the ``schema-tool`` command. To create the schema use the ``create`` command: -:: +.. code-block:: php $ php doctrine orm:schema-tool:create To drop the schema use the ``drop`` command: -:: +.. code-block:: php $ php doctrine orm:schema-tool:drop If you want to drop and then recreate the schema then use both options: -:: +.. code-block:: php $ php doctrine orm:schema-tool:drop $ php doctrine orm:schema-tool:create @@ -263,14 +263,14 @@ options: As you would think, if you want to update your schema use the ``update`` command: -:: +.. code-block:: php $ php doctrine orm:schema-tool:update All of the above commands also accept a ``--dump-sql`` option that will output the SQL for the ran operation. -:: +.. code-block:: php $ php doctrine orm:schema-tool:create --dump-sql @@ -294,7 +294,7 @@ To convert some mapping information between the various supported formats you can use the ``ClassMetadataExporter`` to get exporter instances for the different formats: -:: +.. code-block:: php getExporter('yml', '/path/to/export/yml'); Now you can export some ``ClassMetadata`` instances: -:: +.. code-block:: php getConfiguration()->setMetadataDriverImpl( @@ -353,7 +353,7 @@ First you need to retrieve the metadata instances with the Now you can get an exporter instance and export the loaded metadata to yml: -:: +.. code-block:: php getExporter('yml', '/path/to/export/yml'); @@ -363,11 +363,11 @@ to yml: You can also reverse engineer a database using the ``orm:convert-mapping`` command: -:: +.. code-block:: php $ php doctrine orm:convert-mapping --from-database yml /path/to/mapping-path-converted-to-yml -.. warning:: +.. note:: Reverse Engineering is not always working perfectly depending on special cases. It will only detect Many-To-One diff --git a/manual/en/transactions-and-concurrency.rst b/en/reference/transactions-and-concurrency.rst similarity index 98% rename from manual/en/transactions-and-concurrency.rst rename to en/reference/transactions-and-concurrency.rst index 717783340..56a9c7db7 100644 --- a/manual/en/transactions-and-concurrency.rst +++ b/en/reference/transactions-and-concurrency.rst @@ -33,7 +33,7 @@ The first approach is to use the implicit transaction handling provided by the Doctrine ORM EntityManager. Given the following code snippet, without any explicit transaction demarcation: -:: +.. code-block:: php find('BlogPost', 123456); @@ -301,7 +301,7 @@ See the example code, The form (GET Request): And the change headline action (POST Request): -:: +.. code-block:: php `_. +- The :ref:`concept of owning and inverse sides ` + in bidirectional associations. - If an entity is removed from a collection, the association is removed, not the entity itself. A collection of entities always only represents the association to the containing entities, not the entity itself. -- Collection-valued persistent fields have to be instances of the +- Collection-valued :ref:`persistent fields ` have to be instances of the ``Doctrine\Common\Collections\Collection`` interface. - `See here `_ - for more details. Changes to associations in your code are not synchronized to the database directly, but upon calling ``EntityManager#flush()``. @@ -34,7 +31,7 @@ entities to show examples of association management. See the PHP docblocks of each association in the following example for information about its type and if its the owning or inverse side. -:: +.. code-block:: php find('User', $userId); @@ -176,7 +173,7 @@ The interaction code would then look like in the following snippet In the case of bi-directional associations you have to update the fields on both sides: -:: +.. code-block:: php getFavorites()->add($favoriteComment); @@ -439,7 +436,7 @@ of this chapter. Suppose in our application a user is created whenever he writes his first comment. In this case we would use the following code: -:: +.. code-block:: php find('User', $deleteUserId); @@ -478,7 +475,7 @@ To have Doctrine handle both cases automatically we can change the ``User#commentsAuthored`` property to cascade both the "persist" and the "remove" operation. -:: +.. code-block:: php find('CMS\Article', 1234); @@ -60,7 +60,7 @@ screen. You can even verify that ``$article`` and ``$article2`` are indeed pointing to the same instance by running the following code: -:: +.. code-block:: php find('Article', 1); @@ -157,7 +157,7 @@ A slice of the generated proxy classes code looks like the following piece of code. A real proxy class override ALL public methods along the lines of the ``getName()`` method shown below: -:: +.. code-block:: php persist($user); $em->flush(); -.. warning:: +.. note:: Generated entity identifiers / primary keys are guaranteed to be available after the next successful flush @@ -251,7 +251,7 @@ the ``EntityManager#remove($entity)`` method. By applying the which means that its persistent state will be deleted once ``EntityManager#flush()`` is invoked. -.. warning:: +.. note:: Just like ``persist``, invoking ``remove`` on an entity does NOT cause an immediate SQL DELETE to be issued on the @@ -261,7 +261,7 @@ which means that its persistent state will be deleted once Example: -:: +.. code-block:: php remove($user); @@ -332,7 +332,7 @@ Doctrine will not hold on to any references to a detached entity. Example: -:: +.. code-block:: php detach($entity); @@ -381,7 +381,7 @@ this entity and this copy will subsequently be returned. Example: -:: +.. code-block:: php getUnitOfWork()->size(); @@ -527,7 +536,7 @@ to change tracking (see "Change Tracking Policies") and, of course, memory consumption, so you may want to check it from time to time during development. -.. warning:: +.. note:: Do not invoke ``flush`` after every change to an entity or every single invocation of persist/remove/merge/... This is an @@ -545,12 +554,14 @@ You can get direct access to the Unit of Work by calling ``EntityManager#getUnitOfWork()``. This will return the UnitOfWork instance the EntityManager is currently using. -:: +.. code-block:: php getUnitOfWork(); - **NOTE** Directly manipulating a UnitOfWork is not recommended. +.. note:: + + Directly manipulating a UnitOfWork is not recommended. When working directly with the UnitOfWork API, respect methods marked as INTERNAL by not using them and carefully read the API documentation. @@ -565,7 +576,7 @@ explicitly need to find out what the current state of an entity is in the context of a certain ``EntityManager`` you can ask the underlying ``UnitOfWork``: -:: +.. code-block:: php getUnitOfWork()->getEntityState($entity)) { @@ -610,7 +621,7 @@ identifier / primary key using the ``EntityManager#find($entityName, $id)`` method. Here is an example: -:: +.. code-block:: php `_. +:doc:`the dedicated chapter `. For programmatically building up queries based on conditions that are only known at runtime, Doctrine provides the special ``Doctrine\ORM\QueryBuilder`` class. More information on constructing queries with a QueryBuilder can be found -`in the dedicated chapter `_. +:doc:`in Query Builder chapter `. By Native Queries ~~~~~~~~~~~~~~~~~ @@ -742,7 +753,7 @@ applications that require lots of specialized DQL queries using a custom repository is one recommended way of grouping these queries in a central location. -:: +.. code-block:: php setFileExtension('.xml'); @@ -57,7 +57,7 @@ want to. In order to tell the XmlDriver where to look for your mapping documents, supply an array of paths as the first argument of the constructor, like this: -:: +.. code-block:: php diff --git a/manual/en/yaml-mapping.rst b/en/reference/yaml-mapping.rst similarity index 98% rename from manual/en/yaml-mapping.rst rename to en/reference/yaml-mapping.rst index 9f62eea8d..941ade9ef 100644 --- a/manual/en/yaml-mapping.rst +++ b/en/reference/yaml-mapping.rst @@ -21,7 +21,7 @@ In order to work, this requires certain conventions: - -:: +.. code-block:: php setFileExtension('.yml'); @@ -32,7 +32,7 @@ want to. In order to tell the YamlDriver where to look for your mapping documents, supply an array of paths as the first argument of the constructor, like this: -:: +.. code-block:: php `_. +**clone** nor **wakeup** or :doc:`do so safely <../cookbook/implementing-wakeup-or-clone>`. An entity contains persistable properties. A persistable property is an instance variable of the entity that contains the data which @@ -62,7 +61,7 @@ A first prototype A first simplified design for this domain model might look like the following set of classes: -:: +.. code-block:: php register(); + // See :doc:`Configuration <../reference/configuration>` for up to date autoloading details. $config = new Doctrine\ORM\Configuration(); // (2) @@ -549,7 +543,7 @@ can use whatever suits you best. The second block contains of the instantiation of the ORM Configuration object. Besides the configuration shown in the next blocks there are several others with are all explained in the -`Configuration section of the manual `_. +:doc:`Configuration section of the manual <../reference/configuration>`. The Proxy Configuration is a required block for your application, you have to specify where Doctrine writes the PHP code for Proxy @@ -598,7 +592,7 @@ 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: -:: +.. code-block:: php cd myproject/ doctrine@my-desktop> doctrine orm:schema-tool:create @@ -623,7 +616,7 @@ Doctrine command-line tool: your doctrine command-line client. See the - `Tools section of the manual `_ + :doc:`Tools section of the manual <../reference/tools>` on how to setup the Doctrine console correctly. @@ -631,17 +624,15 @@ During the development you probably need to re-create the database several times when changing the Entity metadata. You can then either re-create the database: -:: +.. code-block:: bash - [console] doctrine@my-desktop> doctrine orm:schema-tool:drop doctrine@my-desktop> doctrine orm:schema-tool:create Or use the update functionality: -:: +.. code-block:: bash - [console] doctrine@my-desktop> doctrine orm:schema-tool:update The updating of databases uses a Diff Algorithm for a given @@ -655,7 +646,7 @@ Writing Entities into the Database Having created the schema we can now start and save entities in the database. For starters we need a create user use-case: -:: +.. code-block:: php find("User", $theReporterId); @@ -758,7 +749,7 @@ mapper for the required view representations. When opening the application, bugs can be paginated through a list-view, which is the first read-only use-case: -:: +.. code-block:: php find("Bug", (int)$theBugId); @@ -881,7 +872,7 @@ write scenarios: However we will soon see another problem with our entities using this approach. Try displaying the engineer's name: -:: +.. code-block:: php description."\n"; @@ -897,7 +888,7 @@ replaced by LazyLoading proxies. Sample code of this proxy generated code can be found in the specified Proxy Directory, it looks like: -:: +.. code-block:: php getDescription()."\n"; @@ -952,7 +943,7 @@ list of all open bugs the user reported or was assigned to. This will be achieved using DQL again, this time with some WHERE clauses and usage of bound parameters: -:: +.. code-block:: php find("Bug", (int)$theBugId); @@ -1024,12 +1015,10 @@ improvement compared to updating all the properties. This tutorial is over here, I hope you had fun. Additional content will be added to this tutorial incrementally, topics will include: -:: - - * Entity Repositories - * More on Association Mappings - * Lifecycle Events triggered in the UnitOfWork - * Ordering of Collections +* Entity Repositories +* More on Association Mappings +* Lifecycle Events triggered in the UnitOfWork +* Ordering of Collections Additional details on all the topics discussed here can be found in the respective manual chapters. diff --git a/generate-docs.sh b/generate-docs.sh index 07aaf048f..33e811f6c 100755 --- a/generate-docs.sh +++ b/generate-docs.sh @@ -1,2 +1,2 @@ #!/bin/bash -sphinx-build manual/en /var/www/docs +sphinx-build en /var/www/docs diff --git a/manual/en.rst b/manual/en.rst deleted file mode 100644 index f66e1b2fd..000000000 --- a/manual/en.rst +++ /dev/null @@ -1,79 +0,0 @@ -Introduction -============ - -Architecture -============ - -Configuration -============= - -Basic Mapping -============= - -Association Mapping -=================== - -Inheritance Mapping -=================== - -Working with objects -==================== - -Working with associations -========================= - -Transactions and Concurrency -============================ - -Events -====== - -Batch processing -================ - -DQL (Doctrine Query Language) -============================= - -Query Builder -============= - -Native SQL -========== - -Change Tracking Policies -======================== - -Partial Objects -=============== - -XML Mapping -=========== - -YAML Mapping -============ - -Annotations Reference -===================== - -PHP Mapping -=========== - -Caching -======= - -Improving Performance -===================== - -Tools -===== - -Metadata Drivers -================ - -Best Practices -============== - -Limitations and Known Issues -============================ - - diff --git a/manual/en.txt b/manual/en.txt deleted file mode 100644 index 95d8bdbec..000000000 --- a/manual/en.txt +++ /dev/null @@ -1,26 +0,0 @@ -# Introduction -# Architecture -# Configuration -# Basic Mapping -# Association Mapping -# Inheritance Mapping -# Working with objects -# Working with associations -# Transactions and Concurrency -# Events -# Batch processing -# DQL (Doctrine Query Language) -# Query Builder -# Native SQL -# Change Tracking Policies -# Partial Objects -# XML Mapping -# YAML Mapping -# Annotations Reference -# PHP Mapping -# Caching -# Improving Performance -# Tools -# Metadata Drivers -# Best Practices -# Limitations and Known Issues \ No newline at end of file diff --git a/manual/en/index.rst b/manual/en/index.rst deleted file mode 100644 index cb638ddbb..000000000 --- a/manual/en/index.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. Doctrine 2 ORM documentation master file, created by - sphinx-quickstart on Mon Nov 1 21:19:39 2010. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to Doctrine 2 ORM's documentation! -========================================== - -Contents: - -.. toctree:: - :maxdepth: 2 - - introduction - architecture - configuration - basic-mapping - association-mapping - inheritance-mapping - working-with-objects - working-with-associations - transactions-and-concurrency - events - batch-processing - dql-doctrine-query-language - query-builder - native-sql - change-tracking-policies - partial-objects - xml-mapping - yaml-mapping - annotations-reference - php-mapping - caching - improving-performance - tools - metadata-drivers - best-practices - limitations-and-known-issues - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` -