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/configuration.rst

@@ -0,0 +1,109 @@
+Configuration
+=============
+
+Initialization and reloading
+----------------------------
+
+The configuration files can be initialized and reloaded at any time using the
+:ref:`phpcr_shell_command_shellconfiginit` and :ref:`phpcr_shell_command_shellconfigreload`
+commands:
+
+.. code-block:: bash
+
+    PHPCRSH> shell:config:init
+    PHPCRSH> shell:config:reload
+
+At time of writing the only configuration file affected by these commands is
+the ``aliases.yml`` file detailed below.
+
+.. _phpcrsh_configuration_aliases:
+
+Aliases
+-------
+
+PHPCRSH supports aliases. Aliases are shortcuts for commands.
+
+Aliases are stored in the file ``$HOME/.phpcrsh/aliases.yml``, which is created
+automatically when launching the PHPCR Shell.
+
+You can list the current aliases with the :ref:`phpcr_shell_command_shellaliaslist` command.
+
+For example:
+
+.. code-block:: bash
+
+    PHPCRSH> ls
+    PHPCRSH> pwd
+    PHPCRSH> refresh
+    PHPCRSH> save
+
+Are all examples of aliases.
+
+Below is the distribution version of this file at time of writing:
+
+.. code-block:: yaml
+
+    # Shell shortcuts
+    aliases: shell:alias:list
+    creload: shell:config:reload
+    cinit: shell:config:init
+
+    # MySQL commands
+    use: workspace:use {arg1}
+    explain: node-type:show {arg1}
+
+    # Filesystem commands
+    cd: shell:path:change {arg1}
+    rm: node:remove {arg1}
+    mv: node:move {arg1} {arg2}
+    pwd: shell:path:show
+    exit: shell:exit
+
+    # Node commands
+    ls: node:list {arg1}
+    ln: node:clone {arg1} {arg2} # symlink, as in ln -s
+    cp: node:copy {arg1} {arg2}
+    cat: node:property:show {arg1}
+    touch: node:property:set {arg1} {arg2} {arg3}
+    mkdir: node:create {arg1} {arg2}
+
+    # Node type commands
+    mixins: node-type:list "^mix:"
+    nodetypes: node-type:list {arg1}
+    ntedit: node-type:edit {arg1}
+    ntshow: node-type:show {arg1}
+
+    # Workspace commands
+    workspaces: workspace:list
+
+    # Namespsce commands
+    namespaces: workspace:namespace:list {arg1}
+    nsset: workspace:namespace:register
+
+    # Editor commands
+    vi: node:edit {arg1} {arg2}
+    vim: node:edit {arg1} {arg2}
+    nano: node:edit {arg1} {arg2}
+
+    # GNU commands
+    man: help {arg1}
+
+    # Version commands
+    checkin: version:checkin {arg1}
+    ci: version:checkin {arg1}
+    co: version:checkout {arg1}
+    checkout: version:checkout {arg1}
+    cp: version:checkpoint {arg1}
+    checkpoint: version:checkpoint {arg1}
+    vhist: version:history {arg1}
+    versions: version:history {arg1}
+
+    # Session commands
+    save: session:save
+    refresh: session:refresh
+
+For a full reference enter in the shell:
+
+.. code-block:: bash
+
+    PHPCRSH> shell:alias:list

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,11 @@
+PHPCR-Shell
+===========
+
+.. toctree::
+    :maxdepth: 2
+
+    installation
+    connecting
+    interacting
+    configuration
+    reference

phpcr-shell/installation.rst

@@ -0,0 +1,70 @@
+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 a version of `DoctrinePHPCRBundle
+<https://github.com/doctrine/DoctrinePHPCRBundle/>`_ greater than 1.2 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.