Created PHPCR-Shell documentation

index.rst

@@ -9,11 +9,10 @@ Welcome to PHPCR's documentation!
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    book/index
-
-
+   phpcr-shell/index
 
 Indices and tables
 ==================

phpcr-shell/connecting.rst

@@ -0,0 +1,132 @@
+Connecting
+==========
+
+Manually
+--------
+
+.. note::
+
+    The following sections detail how to create a connection, you should
+    however only do this once and create a profile. With a profile you
+    can reuse connection settings, see :ref:`phpcrsh_profile`.
+
+Jackrabbit
+~~~~~~~~~~
+
+The following should work with the default 
+
+.. code-block:: bash
+
+    $ phpcrsh --transport=jackrabbit
+
+Parameters:
+
+- **repo-url**: URL for server, default ``http://localhost:8080/server``
+
+Doctrine-Dbal
+~~~~~~~~~~~~~
+
+General connections
+"""""""""""""""""""
+
+The following is the minimal required to connect to a MySQL database:
+
+.. code-block:: bash
+
+    $ phpcrsh --transport=doctrine-dbal --db-name="mydb"
+
+Parameters:
+
+- **db-name**: Name of database to connect to
+- **db-user**: Username for database, default ``root``
+- **db-password**: Password for datanase, default empty
+- **db-host**: Host for database, default ``localhost``
+- **db-path**: Path to sqlite database
+
+Connect to Sqlite database
+""""""""""""""""""""""""""
+
+.. code-block:: bash
+
+    $ phpcrsh --transport=doctrine-dbal --db-path=/path/to/app.sqlite
+
+More settings
+~~~~~~~~~~~~~
+
+For a full list of settings run:
+
+.. code-block:: bash
+
+    $ phpcrsh --help
+
+.. _phpcrsh_profile:
+
+Profiles
+--------
+
+You can create or use a profile using a single option, `--profile` or `-p` for short.
+
+For example:
+
+.. code-block:: bash
+
+    $ phpcrsh -pmyapp --transport=doctrine-dbal --db-path=/path/to/app.sqlite
+
+Will *create* a profile called ``myapp``. Profiles are stored as YAML files in
+``$HOME:./.phpcrsh/profiles/<profilename>``. And can be manually edited.
+
+To select a profile launch PHPCRSH without any arguments
+
+.. code-block:: bash
+
+    $ phpcrsh
+    No connection parameters, given. Select an existing profile:
+
+      (0) dtlweb
+      (1) ezcmf
+      (2) jackrabbit
+      (3) ratest
+      (4) slinp_test
+      (5) slinptest
+      (6) sulucmf
+
+    Enter profile number: []
+
+To explicitly use a profile use the `-p` option again:
+
+.. code-block:: bash
+
+    $ phpcrsh --profile ratest 
+    # or
+    $ phpcrsh -pratest
+
+.. note::
+
+    A profile is only created if the ``transport`` option is set.
+
+Connect to an embedded PHPCR shell
+----------------------------------
+
+This is the easiest way to connect if you have are developing a Symfony 2 application
+
+See :ref:`phpcrsh-installation-embedded-application`.
+
+You can then connect simply using:
+
+.. code-block:: bash
+
+    $ php app/console phpcr:shell
+
+And you can execute specific commands:
+
+.. code-block:: bash
+
+    $ php app/console phpcr:shell node:list /cms
+
+Queries or commands with options must be escapted due to limitations with the Symfony
+console component:
+
+.. code-block:: bash
+
+    $ php app/console phpcr:shell "SELECT * FROM [nt:unstructured]"
+    $ php app/console phpcr:shell "node:list -L2"

phpcr-shell/index.rst

@@ -0,0 +1,8 @@
+PHPCR-Shell
+===========
+
+.. toctree::
+    :maxdepth: 2
+
+    installation
+    connecting

phpcr-shell/installation.rst

@@ -0,0 +1,69 @@
+Installation
+============
+
+You can install PHPCR Shell either as an embedded application or as a PHAR, or
+you can built it your self (for instance if you want the latest version).
+
+.. _phpcrsh-connecting-installation-as-phar:
+
+Install as a PHAR
+-----------------
+
+The latest release can be downloaded from the `Github releases page
+<https://github.com/doctrine/DoctrinePHPCRBundle/>`_.
+
+After downloading it it is recommended to install it in a path accessible
+by the system, for example:
+
+.. code-block:: bash
+
+    $ sudo mv phpcrsh.sh /usr/local/bin/phpcrsh
+    $ sudo chmod a+x /usr/local/bin/phpcrsh
+
+You can now run PHPCRSH from anywhere:
+
+.. code-block:: bash
+
+    $ phpcrsh --help
+
+.. _phpcrsh-installation-embedded-application:
+
+Install as an embedded application
+----------------------------------
+
+If you are using a Symfony2 application and the `DoctrinePHPCRBundle <https://github.com/doctrine/DoctrinePHPCRBundle/>`_
+then you can easily integrate the PHPCR-Shell.
+
+Simply add the shell to your ``composer.json`` file
+
+.. code-block:: javascript
+
+    { 
+        ...
+        require: {
+            ...
+            "phpcr-shell": "<lastest version here>"
+        }
+        ...
+    }
+
+And you can connect directly:
+
+.. code-block:: bash
+
+    $ php app/console phpcr:shell
+
+Build it from source
+--------------------
+
+PHPSH uses the box PHAR building tool, install it `here <http://box-project.org>`_.
+
+Build the PHAR:
+
+.. code-block:: bash
+
+    $ cd phpcr-shell
+    $ box build
+
+This will produce the file ``phpcr.phar``, see :ref:`phpcrsh-connecting-installation-as-phar` for
+further instructions.