From a3883eb3064b42cfb4d0f00d4351c3fefc67b3be Mon Sep 17 00:00:00 2001 From: Benjamin Eberlei Date: Sat, 16 Jun 2012 12:12:04 +0200 Subject: [PATCH] Reworked docs towards composer, simplified chapters --- en/index.rst | 2 +- en/reference/architecture.rst | 69 +++++- en/reference/configuration.rst | 16 +- en/reference/installation.rst | 103 +++++++++ en/reference/introduction.rst | 403 --------------------------------- en/reference/tools.rst | 2 +- 6 files changed, 172 insertions(+), 423 deletions(-) create mode 100644 en/reference/installation.rst delete mode 100644 en/reference/introduction.rst diff --git a/en/index.rst b/en/index.rst index 3841e0654..4a9d74839 100644 --- a/en/index.rst +++ b/en/index.rst @@ -30,8 +30,8 @@ Getting Started :doc:`In 10 quick steps ` * **Reference**: - :doc:`Introduction ` | :doc:`Architecture ` | + :doc:`Installation ` | :doc:`Configuration ` | :doc:`Tools ` | :doc:`Limitations and knowns issues ` diff --git a/en/reference/architecture.rst b/en/reference/architecture.rst index c3508bf7b..54122bcf1 100644 --- a/en/reference/architecture.rst +++ b/en/reference/architecture.rst @@ -5,8 +5,69 @@ This chapter gives an overview of the overall architecture, terminology and constraints of Doctrine 2. It is recommended to read this chapter carefully. +Using an Object-Relational Mapper +--------------------------------- + +As the term ORM already hints at, Doctrine 2 aims to simplify the +translation between database rows and the PHP object model. The +primary use case for Doctrine are therefore applications that +utilize the Object-Oriented Programming Paradigm. For applications +that not primarily work with objects Doctrine 2 is not suited very +well. + +Requirements +------------ + +Doctrine 2 requires a minimum of PHP 5.3.0. For greatly improved +performance it is also recommended that you use APC with PHP. + +Doctrine 2 Packages +------------------- + +Doctrine 2 is divided into three main packages. + +- Common +- DBAL (includes Common) +- ORM (includes DBAL+Common) + +This manual mainly covers the ORM package, sometimes touching parts +of the underlying DBAL and Common packages. The Doctrine code base +is split in to these packages for a few reasons and they are to... + + +- ...make things more maintainable and decoupled +- ...allow you to use the code in Doctrine Common without the ORM + or DBAL +- ...allow you to use the DBAL without the ORM + +The Common Package +~~~~~~~~~~~~~~~~~~ + +The Common package contains highly reusable components that have no +dependencies beyond the package itself (and PHP, of course). The +root namespace of the Common package is ``Doctrine\Common``. + +The DBAL Package +~~~~~~~~~~~~~~~~ + +The DBAL package contains an enhanced database abstraction layer on +top of PDO but is not strongly bound to PDO. The purpose of this +layer is to provide a single API that bridges most of the +differences between the different RDBMS vendors. The root namespace +of the DBAL package is ``Doctrine\DBAL``. + +The ORM Package +~~~~~~~~~~~~~~~ + +The ORM package contains the object-relational mapping toolkit that +provides transparent relational persistence for plain PHP objects. +The root namespace of the ORM package is ``Doctrine\ORM``. + +Terminology +----------- + Entities --------- +~~~~~~~~ An entity is a lightweight, persistent domain object. An entity can be any regular PHP class observing the following restrictions: @@ -38,7 +99,9 @@ polymorphic queries. Both abstract and concrete classes can be entities. Entities may extend non-entity classes as well as entity classes, and non-entity classes may extend entity classes. - **TIP** The constructor of an entity is only ever invoked when +.. note:: + + The constructor of an entity is only ever invoked when *you* construct a new instance with the *new* keyword. Doctrine never calls entity constructors, thus you are free to use them as you wish and even have it require arguments of any type. @@ -101,7 +164,7 @@ work well with any potential cyclic object references (at least we did not find a way yet, if you did, please contact us). The EntityManager ------------------ +~~~~~~~~~~~~~~~~~ The ``EntityManager`` class is a central access point to the ORM functionality provided by Doctrine 2. The ``EntityManager`` API is diff --git a/en/reference/configuration.rst b/en/reference/configuration.rst index 6d4f291a7..679997be8 100644 --- a/en/reference/configuration.rst +++ b/en/reference/configuration.rst @@ -4,25 +4,11 @@ Configuration Bootstrapping Doctrine is a relatively simple procedure that roughly exists of four steps: -- Installation +- `Installation ` - Making sure Doctrine class files can be loaded on demand. - Obtaining an EntityManager instance. - Optional: Configuration of the Console Tool -Installation ------------- - -`Composer `_ is the suggested installation method for Doctrine. -Define the following requirement in your ``composer.json`` file: - - { - "require": { - "doctrine/orm": "*" - } - } - -Then run the composer command. - Class loading ------------- diff --git a/en/reference/installation.rst b/en/reference/installation.rst new file mode 100644 index 000000000..43cb28e70 --- /dev/null +++ b/en/reference/installation.rst @@ -0,0 +1,103 @@ +Installation +============ + +Doctrine can be installed many different ways. We will describe all the different ways and you can choose which one suits you best. + +Composer +-------- + +`Composer `_ is the suggested installation method for Doctrine. +Define the following requirement in your ``composer.json`` file: + +:: + + { + "require": { + "doctrine/orm": "*" + } + } + +Then run the composer command and you are done. Continue with the +:doc:`Configuration `. + +PEAR +---- + +You can easily install any of the three Doctrine packages from the +PEAR command line installation utility. + +To install just the ``Common`` package you can run the following +command: + +.. code-block:: bash + + $ sudo pear install pear.doctrine-project.org/DoctrineCommon- + +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- + + +.. note:: + + The ```` tag above represents the version you + want to install. For example if the current version at the time of + writing this is ``2.2.2`` for the ORM, so you could install it + like the following: + + .. code-block:: bash + + $ sudo pear install pear.doctrine-project.org/DoctrineORM-2.2.2 + +Package Download +---------------- + +You can also use Doctrine 2 by downloading the latest release +package from +`the download page `_. + +See the configuration section on how to configure and bootstrap a +downloaded version of Doctrine. + +GitHub +------ + +Alternatively you can clone the latest version of Doctrine 2 via +GitHub.com: + +.. code-block:: php + + $ git clone git://github.com/doctrine/doctrine2.git doctrine + +This downloads all the sources of the ORM package. You need to +initialize the Github submodules for the Common and DBAL package +dependencies: + +.. code-block:: php + + $ git submodule init + $ git submodule update + +This updates your Git checkout to use the Doctrine and Doctrine +package versions that are recommended for the cloned Master version +of Doctrine 2. + +See the configuration chapter on how to configure a Github +installation of Doctrine with regards to autoloading. + +.. note:: + + You should not combine the Doctrine-Common, Doctrine-DBAL and + Doctrine-ORM master commits with each other in combination. The ORM + may not work with the current Common or DBAL master versions. + Instead the ORM ships with the Git Submodules that are required. diff --git a/en/reference/introduction.rst b/en/reference/introduction.rst deleted file mode 100644 index 84c2b5f04..000000000 --- a/en/reference/introduction.rst +++ /dev/null @@ -1,403 +0,0 @@ -Introduction -============ - -Welcome -------- - -Doctrine 2 is an object-relational mapper (ORM) for PHP 5.3.0+ that -provides transparent persistence for PHP objects. It sits on top of -a powerful database abstraction layer (DBAL). Object-Relational -Mappers primary task is the transparent translation between (PHP) -objects and relational database rows. - -One of Doctrines key features is the option to write database -queries in a proprietary object oriented SQL dialect called -Doctrine Query Language (DQL), inspired by Hibernates HQL. Besides -DQLs slight differences to SQL it abstracts the mapping between -database rows and objects considerably, allowing developers to -write powerful queries in a simple and flexible fashion. - -Disclaimer ----------- - -This is the Doctrine 2 reference documentation. Introductory guides -and tutorials that you can follow along from start to finish, like -the "Guide to Doctrine" book known from the Doctrine 1.x series, -will be available at a later date. - -Using an Object-Relational Mapper ---------------------------------- - -As the term ORM already hints at, Doctrine 2 aims to simplify the -translation between database rows and the PHP object model. The -primary use case for Doctrine are therefore applications that -utilize the Object-Oriented Programming Paradigm. For applications -that not primarily work with objects Doctrine 2 is not suited very -well. - -Requirements ------------- - -Doctrine 2 requires a minimum of PHP 5.3.0. For greatly improved -performance it is also recommended that you use APC with PHP. - -Doctrine 2 Packages -------------------- - -Doctrine 2 is divided into three main packages. - - -- Common -- DBAL (includes Common) -- ORM (includes DBAL+Common) - -This manual mainly covers the ORM package, sometimes touching parts -of the underlying DBAL and Common packages. The Doctrine code base -is split in to these packages for a few reasons and they are to... - - -- ...make things more maintainable and decoupled -- ...allow you to use the code in Doctrine Common without the ORM - or DBAL -- ...allow you to use the DBAL without the ORM - -The Common Package -~~~~~~~~~~~~~~~~~~ - -The Common package contains highly reusable components that have no -dependencies beyond the package itself (and PHP, of course). The -root namespace of the Common package is ``Doctrine\Common``. - -The DBAL Package -~~~~~~~~~~~~~~~~ - -The DBAL package contains an enhanced database abstraction layer on -top of PDO but is not strongly bound to PDO. The purpose of this -layer is to provide a single API that bridges most of the -differences between the different RDBMS vendors. The root namespace -of the DBAL package is ``Doctrine\DBAL``. - -The ORM Package -~~~~~~~~~~~~~~~ - -The ORM package contains the object-relational mapping toolkit that -provides transparent relational persistence for plain PHP objects. -The root namespace of the ORM package is ``Doctrine\ORM``. - -Installing ----------- - -Doctrine can be installed many different ways. We will describe all -the different ways and you can choose which one suits you best. - -PEAR -~~~~ - -You can easily install any of the three Doctrine packages from the -PEAR command line installation utility. - -To install just the ``Common`` package you can run the following -command: - -.. code-block:: bash - - $ sudo pear install pear.doctrine-project.org/DoctrineCommon- - -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- - - -.. note:: - - The ```` tag above represents the version you - want to install. For example if the current version at the time of - writing this is ``2.0.7`` for the ORM, so you could install it - like the following: - - .. code-block:: bash - - $ sudo pear install pear.doctrine-project.org/DoctrineORM-2.0.7 - - -When you have a package installed via PEAR you can require and load -the ``ClassLoader`` with the following code. - -.. code-block:: php - - `_. - -See the configuration section on how to configure and bootstrap a -downloaded version of Doctrine. - -GitHub -~~~~~~ - -Alternatively you can clone the latest version of Doctrine 2 via -GitHub.com: - -.. code-block:: php - - $ git clone git://github.com/doctrine/doctrine2.git doctrine - -This downloads all the sources of the ORM package. You need to -initialize the Github submodules for the Common and DBAL package -dependencies: - -.. code-block:: php - - $ git submodule init - $ git submodule update - -This updates your Git checkout to use the Doctrine and Doctrine -package versions that are recommended for the cloned Master version -of Doctrine 2. - -See the configuration chapter on how to configure a Github -installation of Doctrine with regards to autoloading. - - **NOTE** - - You should not combine the Doctrine-Common, Doctrine-DBAL and - Doctrine-ORM master commits with each other in combination. The ORM - may not work with the current Common or DBAL master versions. - Instead the ORM ships with the Git Submodules that are required. - - -Subversion -~~~~~~~~~~ - - **NOTE** - - Using the SVN Mirror is not recommended. It only allows access to - the latest master commit and does not automatically fetch the - submodules. - - -If you prefer subversion you can also checkout the code from -GitHub.com through the subversion protocol: - -.. code-block:: php - - $ svn co http://svn.github.com/doctrine/doctrine2.git doctrine2 - -However this only allows you to check out the current master of -Doctrine 2, without the Common and DBAL dependencies. You have to -grab them yourself, but might run into version incompatibilities -between the different master branches of Common, DBAL and ORM. - -Sandbox Quickstart ------------------- - - **NOTE** The sandbox is only available via the Doctrine2 Github - Repository or soon as a separate download on the downloads page. - You will find it in the $root/tools/sandbox folder. - - -The sandbox is a pre-configured environment for evaluating and -playing with Doctrine 2. - -Overview -~~~~~~~~ - -After navigating to the sandbox directory, you should see the -following structure: - -.. code-block:: php - - sandbox/ - Entities/ - Address.php - User.php - xml/ - Entities.Address.dcm.xml - Entities.User.dcm.xml - yaml/ - Entities.Address.dcm.yml - Entities.User.dcm.yml - cli-config.php - doctrine - doctrine.php - index.php - -Here is a short overview of the purpose of these folders and -files: - - -- The ``Entities`` folder is where any model classes are created. - Two example entities are already there. -- The ``xml`` folder is where any XML mapping files are created - (if you want to use XML mapping). Two example mapping documents for - the 2 example entities are already there. -- The ``yaml`` folder is where any YAML mapping files are created - (if you want to use YAML mapping). Two example mapping documents - for the 2 example entities are already there. -- The ``cli-config.php`` contains bootstrap code for a - configuration that is used by the Console tool ``doctrine`` - whenever you execute a task. -- ``doctrine``/``doctrine.php`` is a command-line tool. -- ``index.php`` is a basic classical bootstrap file of a php - application that uses Doctrine 2. - -Mini-tutorial -~~~~~~~~~~~~~ - - -1) From within the tools/sandbox folder, run the following command - and you should see the same output. - - $ php doctrine orm:schema-tool:create Creating database schema... - Database schema created successfully! - -2) Take another look into the tools/sandbox folder. A SQLite - database should have been created with the name - ``database.sqlite``. - -3) Open ``index.php`` and at the bottom edit it so it looks like - the following: - - -.. code-block:: php - - setName('Garfield'); - $em->persist($user); - $em->flush(); - - echo "User saved!"; - - -Open index.php in your browser or execute it on the command line. -You should see the output "User saved!". - - -4) Inspect the SQLite database. Again from within the tools/sandbox - folder, execute the following command: - - $ php doctrine dbal:run-sql "select \* from users" - - -You should get the following output: - -.. code-block:: php - - array(1) { - [0]=> - array(2) { - ["id"]=> - string(1) "1" - ["name"]=> - string(8) "Garfield" - } - } - -You just saved your first entity with a generated ID in an SQLite -database. - - -5) Replace the contents of index.php with the following: - - -.. code-block:: php - - createQuery('select u from Entities\User u where u.name = ?1'); - $q->setParameter(1, 'Garfield'); - $garfield = $q->getSingleResult(); - - echo "Hello " . $garfield->getName() . "!"; - - -You just created your first DQL query to retrieve the user with the -name 'Garfield' from an SQLite database (Yes, there is an easier -way to do it, but we wanted to introduce you to DQL at this point. -Can you **find** the easier way?). - - **TIP** When you create new model classes or alter existing ones - you can recreate the database schema with the command - ``doctrine orm:schema-tool --drop`` followed by - ``doctrine orm:schema-tool --create``. - - - -6) Explore Doctrine 2! - -Instead of reading through the reference manual we also recommend to look at the tutorials: - -:doc:`Getting Started Tutorial <../tutorials/getting-started>` - - diff --git a/en/reference/tools.rst b/en/reference/tools.rst index 69babfc27..6f01b0527 100644 --- a/en/reference/tools.rst +++ b/en/reference/tools.rst @@ -8,7 +8,7 @@ The Doctrine Console is a Command Line Interface tool for simplifying common tasks during the development of a project that uses Doctrine 2. -Take a look at the `Configuration ` for more +Take a look at the :doc:`Configuration ` for more information how to setup the console command. Getting Help