Split tutorial into book

Author: dantleech

book/conclusion.rst

@@ -0,0 +1,12 @@
+Conclusion and further reading
+==============================
+
+We hope this tutorial helps to get you started. If you miss anything, have suggestions or questions, please contact us on [email protected] or #jackalope on irc.freenode.net
+
+Further reading
+---------------
+
+Browse through the [API documentation](http://phpcr.github.com/doc/html/index.html) to see what each of the core elements mentioned in the introduction can do.
+
+To fully understand the concepts behind the content repository API, we suggest reading [the Java content repository specification](http://www.day.com/specs/jcr/2.0/index.html) and
+then the [simplifications we did for PHP](https://github.com/phpcr/phpcr/blob/master/doc/JCR_TO_PHPCR.txt).

book/getting_started.rst

@@ -0,0 +1,74 @@
+Introduction and Getting Stated
+===============================
+
+This is an introduction into the PHP content repository. You will mostly see code examples. It should work with any PHPCR implementation. We propose using [Jackalope Jackrabbit](https://github.com/jackalope/jackalope-jackrabbit) to get started as it supports all features described here.
+
+Installing Jackalope
+--------------------
+
+Just follow the README of the [jackalope-jackrabbit](https://github.com/jackalope/jackalope-jackrabbit/blob/master/README.md) repository.
+
+Browser to see what is in the repository
+----------------------------------------
+
+There are currently two options for browsing and modifying the contents of the PHPCR repository.
+
+- <a href="/documentation/phpcr-shell">PHPCR Shell</a>: Aims to provide a full command line shell interface to PHPCR content repositories. A pre-compiled PHAR archive is available on the github homepage.
+- <a href="https://github.com/marmelab/phpcr-browser">Marmelab PHPCR Browser</a>: A web based PHPCR browser.
+
+In a nutshell
+-------------
+
+The shortest self-contained example should output a line with 'value':
+
+.. code-block:: php
+
+    <?php
+    require("/path/to/jackalope-jackrabbit/vendor/autoload.php");
+
+    $factoryclass = '\Jackalope\RepositoryFactoryJackrabbit';
+    $parameters = array('jackalope.jackrabbit_uri' => 'http://localhost:8080/server');
+    // end of implementation specific configuration
+
+    $factory = new $factoryclass();
+    $repository = $factory->getRepository($parameters);
+    $credentials = new \PHPCR\SimpleCredentials('admin','admin');
+    $session = $repository->login($credentials, 'default');
+    $root = $session->getRootNode();
+    $node = $root->addNode('test', 'nt:unstructured');
+    $node->setProperty('prop', 'value');
+    $session->save();
+
+    // data is stored now. in a follow-up request you can do
+    $node = $session->getNode('/test');
+    echo $node->getPropertyValue('prop'); // outputs "value"
+
+Still with us? Good, lets get in a bit deeper...
+
+Get some data into the repository
+---------------------------------
+
+We will discuss the import feature in more detail later, but to have some data, we just import something here. Create an XML file test.xml like this:
+
+.. code-block:: xml
+
+    <data xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0">
+        <node title="Test" content="This is some test content" />
+        <sibling title="Test" content="This is another test content">
+            <child1 title="Child1 title" />
+            <child2 title="Child2 title" />
+            <otherchild title="Otherchild title"/>
+            <yetanother title="Yetanother title">
+                <child title="Child title" />
+            </yetanother>
+        </sibling>
+    </data>
+
+Now import this into the repository:
+
+.. code-block:: php
+
+    <?php
+    $session->importXML('/', 'test.xml', \PHPCR\ImportUUIDBehaviorInterface::IMPORT_UUID_CREATE_NEW);
+    $session->save();
+

book/import_export.rst

@@ -0,0 +1,66 @@
+Import and export data
+======================
+
+As promised, here are some more details on importing and exporting data. There
+are two formats:
+
+* The *document view* translates the data into a XML document with node names
+    as xml elements and properties as attributes and thus very readable. Type
+    information is lost, and illegal XML characters are encoded.
+* The *system view* is a more strict XML document defining the exact structure
+    of the repository with all type information. However, it is more verbose.
+
+As an analogy, think about an SQL dump file with SQL statements and the dump of
+an SQL table into a csv file. You can restore the data from both, but the SQL
+dump knows every detail about your field types and so on while the CSV just
+knows the data.
+
+When exporting, you tell explicitly to which format you want to export:
+
+.. code-block:: php
+
+    <?php
+    $file = fopen('/tmp/document.xml', 'w+');
+
+    // dump the tree at /foo/bar into a document view file
+    $session->exportDocumentView(
+        '/data/sibling',
+        $file,
+        true, // skip binary properties to not have large files in the dump
+        false // recursivly output the child nodes as well
+    );
+
+    fclose($file);
+
+    $file = fopen('/tmp/system.xml', 'w+');
+    // export the tree at /foo/bar into a system view xml file
+    $session->exportSystemView(
+        '/data/sibling',
+        $file,
+        false, // do not skip binary properties
+        false
+    );
+
+    fclose($file);
+
+Importing detects the format automatically. If the document is a valid JCR
+system view, it is interpreted according to that format, otherwise if it is a
+valid XML document it is imported as document:
+
+.. code-block:: php
+
+    <?php
+    $filename = 'dump.xml';
+    $session->getRootNode()->addNode('imported_data', 'nt:unstructured');
+    $session->importXML(
+        '/imported_data', // attach the imported data at this node
+        $filename,
+        ImportUUIDBehaviorInterface::IMPORT_UUID_CREATE_NEW
+    );
+
+When importing nodes with a uuid, a couple of different behaviors can be used:
+
+* `IMPORT_UUID_CREATE_NEW`: Create new UUIDs for nodes that are imported, so you never get collisions.
+* `IMPORT_UUID_COLLISION_THROW`: Throw an exception if a node with the same UUID already exists.
+* `IMPORT_UUID_COLLISION_REMOVE_EXISTING`: Remove an existing node if an imported node has the same UUID.
+* `IMPORT_UUID_COLLISION_REPLACE_EXISTING`: Replace existing node with the imported node. This can lead to the imported data being put in various places.

book/index.rst

@@ -0,0 +1,23 @@
+The Book
+========
+
+.. toctree::
+
+    getting_started
+    introduction
+    reading_data_and_traversal
+    references
+    shareable_nodes
+    same_name_siblings
+    query
+    writing
+    orderable_child_nodes
+    locking
+    versioning
+    transactions
+    import_export
+    observation
+    node_types
+    search
+    performance
+    conclusion

book/introduction.rst

@@ -0,0 +1,37 @@
+Introduction
+============
+
+In the following chapters, we will show how to use the API. But first, you
+need a very brief overview of the core elements of PHPCR. After reading this
+tutorial, you should browse through the API documentation to get an idea what
+operations you can do on each of those elements. See the conclusions for links
+if you want to have more background.
+
+It is important to know about the following concepts:
+
+* **Node, Property**: An object model for data structured similar to XML. A
+  node is like the xml element, the property like the xml attribute.
+  Properties are acquired from their nodes or directly from the session by
+  their path. Nodes are acquired from parent nodes or from the session by
+  their path. Both are Item, sharing the methods of that base interface. Names
+  can be namespaced as in xml, and additionally may contain whitespaces or
+  other not xml-legal characters.
+* **Session**: The authenticated connection to one workspace in the
+  repository. Repository and workspace are immutable inside the Session. The
+  session is the main interface to interact with the actual data. Sessions are
+  acquired from a repository
+* **Repository**: Linking to one storage location with possibly many
+  workspaces. Repositories are created with the help of the repository
+  factory.
+* **RepositoryFactory**: Create repository instances for your implementation
+  with implementation specific parameters.
+* **Workspace**: Provides general operations on the workspace of the Session it is acquired from.
+
+Note on Implementation PHPCR Support
+------------------------------------
+
+PHPCR is a modular standard and has a built-in way to discover the
+capabilities of your implementation. Therefore implementations do not
+have to support all sections of the specification.
+
+TODO: Add a section about capability testing to show how to write portable code.

book/locking.rst

@@ -0,0 +1,41 @@
+Locking
+=======
+
+In PHPCR, you can lock nodes to prevent concurrency issues. There is two basic types of locks:
+
+* Session based locks are only kept until your session ends and released automatically on logout.
+* If a lock is not session based, it is identified by a lock token and stays in place until it times out
+
+Note that jackalope currently only implements session based locks:
+
+.. code-block:: php
+
+    <?php
+    //get the node from the session
+    $node = $session->getNode('/data/sibling');
+    //the node has to be lockable
+    $node->addMixin('mix:lockable');
+    $session->save(); //node needs to be clean before locking
+
+    // get the lock manager
+    $workspace = $session->getWorkspace();
+    $lockManager = $workspace->getLockManager();
+    var_dump($lockManager->isLocked('/data/sibling')); // should be false
+    $lockManager->lock('/data/sibling', true, true); // lock child nodes as well, release when session closed
+    // now only this session may change the node //sibling and its descendants
+    var_dump($lockManager->isLocked('/data/sibling')); // should be true
+    var_dump($lockManager->isLocked('/data/sibling/child1')); // should be true because we locked deep
+
+    // getting the lock from LockManager is not yet implemented with jackalope-jackrabbit
+    $lock = $lockManager->getLock('/data/sibling');
+    var_dump($lock->isLockOwningSession()); // true, this is our lock, not somebody else's
+    var_dump($lock->getSecondsRemaining()); // PHP_INT_MAX because this lock has no timeout
+    var_dump($lock->isLive()); // true
+
+    $node = $lock->getNode(); // this gets us the node for /sibling
+    $node === $lockManager->getLock('/data/sibling')->getNode(); // getnode always returns the lock owning node
+
+    // now unlock the node again
+    $lockManager->unlock('/data/sibling'); // we could also let $session->logout() unlock when using session based lock
+    var_dump($lockManager->isLocked('/data/sibling')); // false
+    var_dump($lock->isLive()); // false

book/node_types.rst

@@ -0,0 +1,15 @@
+Node Types
+==========
+
+PHPCR supports node types. Node types define what properties and children a node can or must have. The JCR specification explains exhaustivly what node types exist and what they are required to have or not: `JCR 2.0: 3.7.11 Standard Application Node Types <http://www.day.com/specs/jcr/2.0/3_Repository_Model.html#3.7.11%20Standard%20Application%20Node%20Types>`_
+
+In a nutshell:
+
+* `nt:unstructured` does not define any required properties but allows any property or child.
+* `nt:file` and `nt:folder` are built-in node types useful to map a file structure in the repository. (With jackalope-jackrabbit, files and folders are exposed over webdav)
+* If you **do not** want to enforce a schema on your node, use
+  `nt:unstructured`.
+* If you need to store additional properties or children on existing node types like files, note that while a node can have only one primary type, every node can have any mixin types. Define a mixin type declaring your additional properties, register it with PHPCR and addMixin it to the nodes that need it.
+
+You can define your own node types if you want the equivalent of a strictly defined database structure. See `JCR 2.0: 3.7 Node Types <http://www.day.com/specs/jcr/2.0/3_Repository_Model.html#3.7%20Node%20Types>`_ and `JCR 2.0: 19 Node Type Management <http://www.day.com/specs/jcr/2.0/19_Node_Type_Management.html>`_ / `PHPCR Node Type Namespace <http://phpcr.github.io/doc/html/index.html>`_.
+

book/observation.rst

@@ -0,0 +1,39 @@
+Observation
+===========
+
+Observation enables an application to receive notifications of persistent changes to a workspace.
+JCR defines a general event model and specific APIs for asynchronous and journaled observation.
+A repository may support asynchronous observation, journaled observation or both.
+
+Note that Jackrabbit supports the full observation API but Jackalope currently only implements event journal reading.
+
+Write operations in Jackalope will generate journal entries as expected.
+
+.. code-block:: php
+
+    <?php
+    use PHPCR\Observation\EventInterface; // Contains the constants for event types
+
+    // Get the observation manager
+    $workspace = $session->getWorkspace();
+    $observationManager = $workspace->getObservationManager();
+
+    // Get the unfiltered event journal and go through its content
+    $journal = $observationManager->getEventJournal();
+    $journal->skipTo(strtotime('-1 day')); // Skip all the events prior to yesterday
+    foreach ($journal as $event) {
+        // Do something with $event (it's a Jackalope\Observation\Event instance)
+        echo $event->getType() . ' - ' . $event->getPath();
+    }
+
+    // Filtering and using the journal as an iterator
+    // You can filter the event journal on several criteria, here we keep events for node and properties added
+    $journal = $observationManager->getEventJournal(EventInterface::NODE_ADDED | EventInterface::PROPERTY_ADDED);
+
+    while ($journal->valid()) {
+        $event = $journal->current();
+        // Do something with $event
+        $journal->next();
+    }
+
+

book/orderable_child_nodes.rst

@@ -0,0 +1,25 @@
+Orderable child nodes
+=====================
+
+While moving is about changing the parent of a node, ordering is used to set the
+position inside the child list. Preserving and altering order is an optional
+feature of PHPCR.
+
+The only method needed is Node::orderBefore
+
+.. code-block:: php
+
+    <?php
+    //get the node from the session
+    $node = $session->getNode('/data/node');
+
+    $node->addNode('first');
+    $node->addNode('second'); // new nodes are added to the end of the list
+    // order is: first, second
+
+    // ordering is done on the parent node. the first argument is the name of
+    // the child node to be reordered, the second the name of the node to moved
+    // node is placed before
+    $node->orderBefore('second', 'first');
+    // now the order is: second, first
+

book/performance.rst

@@ -0,0 +1,27 @@
+Performance considerations
+==========================
+
+While PHPCR can perform reasonably well, you should be careful. You are working with an object model mapping interlinked data. Implementations are supposed to lazy load data only when necessary. But you should take care to only request what you actually need.
+
+The implementations will also use some sort of storage backend (Jackrabbit, (no)SQL database, ...). There might be a huge performance impact in configuring that storage backend optimally. Look into your implementation documentation if there are recommendations how to optimize storage.
+
+One thing *not* to worry about is requesting the same node with Session::getNode or Node::getNode/s several times. You always get the same object instance back without overhead.
+
+
+Only request what you need
+--------------------------
+
+emember that you can filter nodes on Node::getNodes if you only need a list of specific nodes or all nodes in some namespace.
+
+The values of binary properties can potentially have a huge size and should only loaded when really needed. If you just need the size, you can get the property instance and do a $property->getSize() instead of filesize($node->getPropertyValue). Any decent implementation will not preload the binary stream when you access the property object.
+
+When getting the properties from a node, you can use Node::getPropertiesValues(filter, false). This allows the implementation to avoid instantiating Property objects for the property values (and saves you coding). The second boolean parameter tells wheter to dereference reference properties. If you do not need the referenced objects, pass false and you will get the UUID or path strings instead of node objects.(If you need one of them, you can still get it with Session::getNodeByIdentifier. But then the implementation will certainly not be able to optimize if you get several referenced nodes.)
+
+
+But request in one call as much as possible of what you need
+------------------------------------------------------------
+
+If you need to get several nodes where you know the paths, use Session::getNodes with an array of those nodes to get all of them in one batch, saving round trip time to the storage backend.
+
+lso use Node::getNodes with a list of nodes rather than repeatedly calling Node::getNode.
+