## Getting Started

### Minimal Setup
1. **Installation**
   ```bash
   composer require phpcr/phpcr-shell

Ensure your project uses a PHPCR-compatible repository (e.g., Jackalope for Doctrine DBAL-backed repositories). Note for Symfony 8 users: This release explicitly supports Symfony 8 projects.

Basic Usage Run the shell via Artisan (if integrated) or directly:
```
vendor/bin/phpcr-shell
```
Authenticate with your repository credentials (configured in .phpcr-shell.ini or via CLI args).
First Use Case List root nodes to inspect repository structure:
```
ls /
```
Navigate to a node and query its properties:
```
cd /path/to/node
get *
```

Implementation Patterns

Workflows

Repository Exploration
- Traversal: Use ls, cd, and pwd to navigate the repository hierarchy.
- Property Inspection: Fetch node properties with get <property-name> or get * for all.
- Querying: Execute XPath queries directly:
```
xpath //element(*, nt:folder)
```
Node Management
- Create/Update: Use setprop to modify properties or mkfile/mkdir to create nodes.
```
setprop jcr:title "New Title"
mkfile --type nt:file new-file.txt
```
- Bulk Operations: Pipe output to scripts for automation (e.g., ls / | xargs -I {} get {} > properties.log).

Integration with Laravel/Symfony

Artisan Command (Laravel): Extend phpcr-shell as a custom Artisan command for seamless CLI access:

// app/Console/Commands/PhpcrShellCommand.php
use Symfony\Component\Process\Process;

protected $signature = 'phpcr:shell';
public function handle() {
    $process = new Process(['vendor/bin/phpcr-shell']);
    $process->run();
    $this->output->write($process->getOutput());
}

Symfony Console Command: For Symfony 8 projects, create a custom command:

// src/Command/PhpcrShellCommand.php
namespace App\Command;

use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Process\Process;

class PhpcrShellCommand extends Command
{
    protected static $defaultName = 'app:phpcr-shell';
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $process = new Process(['vendor/bin/phpcr-shell']);
        $process->run();
        $output->write($process->getOutput());
        return $process->getExitCode();
    }
}

Environment-Specific Configs: Override .phpcr-shell.ini per environment (e.g., .phpcr-shell.production.ini).

CI/CD Pipelines Use phpcr-shell in deployment scripts to validate repository state:
```
vendor/bin/phpcr-shell -f deploy-checks.txt
```
Example deploy-checks.txt:
```
xpath count(//jcr:root) > 0 || exit 1
```

Gotchas and Tips

Pitfalls

Authentication Quirks
- Hardcoded credentials in .phpcr-shell.ini are insecure. Use environment variables or Laravel/Symfony’s .env:
```
[repository]
uri = $REPO_URI
username = $REPO_USER
password = $REPO_PASS
```
- Fix: Symlink .phpcr-shell.ini to environment-specific files (e.g., .phpcr-shell.staging.ini).
Node Type Conflicts
- Attempting to create nodes with unsupported types (e.g., nt:unstructured) may fail silently. Validate types first:
```
xpath //*[@jcr:primaryType='nt:unstructured']
```
Performance with Large Repos
- Avoid get * on deep hierarchies. Use --limit or filter properties:
```
get jcr:* --limit 100
```
Session Management
- Long-running shells may timeout. Reconnect explicitly:
```
reconnect
```

Debugging

Verbose Mode Enable debug output for connection issues:
```
vendor/bin/phpcr-shell -v
```
Repository-Specific Errors
- Jackalope/Doctrine DBAL: Check jackalope.ini for misconfigurations (e.g., wrong connection strings).
- Tip: Redirect output to a log file:
```
vendor/bin/phpcr-shell 2>&1 | tee debug.log
```

Extension Points

Custom Commands Extend functionality by creating wrapper scripts (e.g., backup.sh):

#!/bin/bash
vendor/bin/phpcr-shell <<EOF
xpath //*[@jcr:primaryType='nt:file'] | xargs -I {} get {} > backup-$(date +%s).json
EOF

Laravel/Symfony Service Provider

Laravel: Bind the shell to Laravel’s container for programmatic use:

// app/Providers/PhpcrServiceProvider.php
use Symfony\Component\Process\Process;

public function register() {
    $this->app->singleton('phpcr.shell', function () {
        return new Process(['vendor/bin/phpcr-shell']);
    });
}

Symfony: Register as a service in services.yaml:

services:
    app.phpcr.shell:
        class: Symfony\Component\Process\Process
        arguments: ['vendor/bin/phpcr-shell']

IDE Integration

Use phpcr-shell in phpstorm.meta.php for autocompletion hints:

return [
    'commands' => [
        'phpcr-shell' => 'Shell for PHPCR repositories',
    ],
];

Configuration Tips

Repository URI: Use phpcr:// for Jackalope or http:// for remote repositories.
Timeouts: Adjust in .phpcr-shell.ini:
```
[repository]
timeout = 30
```
Symfony 8 Compatibility: Ensure your composer.json includes Symfony 8 constraints if leveraging Symfony’s new features.


NO_UPDATE_NEEDED would not apply here as the Symfony 8 support warrants updates to the **Implementation Patterns** section, particularly for Symfony users.

Phpcr Shell Laravel Package