A powerful implementation of the PHPCR API.
Jackalope binding for the jackrabbit backend server.
Discuss on [email protected] or visit #jackalope on irc.freenode.net
License: This code is licenced under the apache license. Please see the file LICENSE in this folder.
- php >= 5.3
- libxml version >= 2.7.0 (due to a bug in libxml http://bugs.php.net/bug.php?id=36501)
- phpunit >= 3.6 (if you want to run the tests)
- composer
If you do not yet have composer, install it like this
curl -s http://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin
To install jackalope itselves, run the following in the parent directory of where you want jackalope
git clone git://github.com/jackalope/jackalope-jackrabbit.git
cd jackalope-jackrabbit
php /usr/local/bin/composer.phar install --dev
Note that the --dev parameter is only needed if you want to be able to run the test suite. If you already installed jackalope without the test suite, you need to remove composer.lock before running composer again with the --dev parameter.
Besides the Jackalope repository, you need the Jackrabbit server component. For instructions, see Jackalope Wiki Make sure you have at least the version specified in the VERSION constant of the protocol implementation
If you want to run the tests, please see the README file in the tests folder and check if you told composer to install the suggested dependencies (see Installation)
There are a couple of useful commands to interact with the repository.
To use the console, copy cli-config.php.dist to cli-config.php and configure
the connection parameters.
Then you can run the commands from the jackalope directory with ./bin/jackalope
NOTE: If you are using PHPCR inside of Symfony, the DoctrinePHPCRBundle provides the commands inside the normal Symfony console and you don't need to prepare anything special.
Jackalope specific commands:
jackalope:run:jackrabbit [--jackrabbit_jar[="..."]] [start|stop|status]: Start and stop the Jackrabbit server
Commands available from the phpcr-utils:
phpcr:workspace:create <name>: Create a workspace name in the repositoryphpcr:register-node-types --allow-update [cnd-file]: Register namespaces and node types from a "Compact Node Type Definition" .cnd filephpcr:dump [--sys_nodes[="..."]] [--props[="..."]] [path]: Show the node names under the specified path. If you set sys_nodes=yes you will also see system nodes. If you set props=yes you will additionally see all properties of the dumped nodes.phpcr:purge: Remove all content from the configured repository in the configured workspacephpcr:sql2: Run a query in the JCR SQL2 language against the repository and dump the resulting rows to the console.
Jackalope relies on autoloading. Namespaces and folders are compliant with
PSR-0. You should use the autoload file generated by composer:
vendor/.composer/autoload.php
If you want to integrate jackalope into other PSR-0 compliant code and use your
own classloader, find the mapping in vendor/.composer/autoload_namespaces.php
Once you have autoloading, you need to bootstrap the library. A minimalist sample code to get a PHPCR session with the jackrabbit backend:
$jackrabbit_url = 'http://127.0.0.1:8080/server/';
$user = 'admin';
$pass = 'admin';
$workspace = 'default';
$repository = \Jackalope\RepositoryFactoryJackrabbit::getRepository(
array('jackalope.jackrabbit_uri' => $jackrabbit_url)
);
$credentials = new \PHPCR\SimpleCredentials($user, $pass);
$session = $repository->login($credentials, $workspace);
To use a workspace different than default you need to create it first. The
easiest is to run the command bin/jackalope phpcr:workspace:create <myworkspace>
but you can of course also use the PHPCR API to create workspaces from your code.
The entry point is to create the repository factory. The factory specifies the storage backend as well. From this point on, there are no differences in the usage (except for supported features, that is).
// see Bootstrapping for how to get the session.
$rootNode = $session->getNode("/");
$whitewashing = $rootNode->addNode("www-whitewashing-de");
$session->save();
$posts = $whitewashing->addNode("posts");
$session->save();
$post = $posts->addNode("welcome-to-blog");
$post->addMixin("mix:title");
$post->setProperty("jcr:title", "Welcome to my Blog!");
$post->setProperty("jcr:description", "This is the first post on my blog! Do you like it?");
$session->save();
See PHPCR Tutorial for a more detailed tutorial on how to use the PHPCR API.
Jackalope supports the PHPCR standard query language SQL2 as well as the Query Object Model (QOM) to build queries programmatically. We recommend using the QOM or the QueryBuilder mentioned in the PHPCR Tutorial. They are built to use the best possible query language depending on the capabilities of the backend. A later switching to another PHPCR implementation shouldn't cause any issues then.
Jackalope-Jackrabbit also supports the depricated SQL and XPath query languages from JCR 1.0. Those languages will be suported by Jackrabbit for the forseeable future, but almost certainly won't be supported by other PHPCR implementations. So use them with care and only if you know what you are doing.
One reason for using SQL or XPath is that the newer and more capable SQL2 is not as optimized as the older languages on the Jackrabbit side. Queries with large resultsets are much slower with SQL2 than with XPath or SQL.
However, the best is to use the QueryBuilder mentioned above to let the implementation chose the most efficient query language for your implementation.
If you know that you will need many child nodes of a node you are about to request, you can use Session::setSessionOption with Session::OPTION_FETCH_DEPTH to something bigger than 1. This will prefetch the children to reduce the round trips to the database.
See doc/architecture.md for an introduction how Jackalope is built. Have a look at the source files and generate the phpdoc.
The best overview of what needs to be done are the skipped API tests. Have a look at JackrabbitImplementationLoader to see what is currently not working and start hacking :-)
- Christian Stocker [email protected]
- David Buchmann [email protected]
- Tobias Ebnöther [email protected]
- Roland Schilter [email protected]
- Uwe Jäger [email protected]
- Lukas Kahwe Smith [email protected]
- Daniel Barsotti [email protected]
- and many others