Permalink
Browse files

Reworked docs towards composer, simplified chapters

  • Loading branch information...
1 parent 65e2f60 commit a3883eb3064b42cfb4d0f00d4351c3fefc67b3be @beberlei beberlei committed Jun 16, 2012
View
@@ -30,8 +30,8 @@ Getting Started
:doc:`In 10 quick steps <tutorials/in-ten-quick-steps>`
* **Reference**:
- :doc:`Introduction <reference/introduction>` |
:doc:`Architecture <reference/architecture>` |
+ :doc:`Installation <reference/installation>` |
:doc:`Configuration <reference/configuration>` |
:doc:`Tools <reference/tools>` |
:doc:`Limitations and knowns issues <reference/limitations-and-known-issues>`
@@ -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
@@ -4,25 +4,11 @@ Configuration
Bootstrapping Doctrine is a relatively simple procedure that
roughly exists of four steps:
-- Installation
+- `Installation <reference/installation>`
- Making sure Doctrine class files can be loaded on demand.
- Obtaining an EntityManager instance.
- Optional: Configuration of the Console Tool
-Installation
-------------
-
-`Composer <http://www.getcomposer.org>`_ 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
-------------
@@ -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 <http://www.getcomposer.org>`_ 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 <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-<version>
+
+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-<version>
+
+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-<version>
+
+
+.. note::
+
+ The ``<version>`` 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 <http://www.doctrine-project.org/download>`_.
+
+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.
Oops, something went wrong.

0 comments on commit a3883eb

Please sign in to comment.