Getting Started

Minimal Setup

Installation:
```
composer require chigix/chiji:~1.0.0
```
Requires PHP 5.4+.

Create a config file (/path/to/conf-file.php):

<?php
class ConfigFile extends \Chigi\Chiji\Project\ProjectConfig {
    public function getProjectName() { return "MyApp"; }
    public function getSourceDirs() { return ['app/scripts', 'app/styles']; }
    public function getReleaseDirs() { return ['public/assets']; }
}
return new ConfigFile();

Register the project in your Laravel service provider (e.g., AppServiceProvider):

use Chigi\Chiji\Project\Project;
use Chigi\Chiji\Util\ProjectUtil;

public function boot() {
    $project = new Project(__DIR__.'/conf-file.php');
    ProjectUtil::registerProject($project);
}

Run asset processing via Artisan (create a custom command or use Robo):
```
php artisan chiji:build
```
(Note: Requires a custom Artisan command or Robo integration—see Implementation Patterns.)

First Use Case: Processing LESS/CSS

Add a LESS file (app/styles/main.less) with @require annotations:

@require('bower_components/bootstrap/less/bootstrap.less');
@release('dist', 'main.css');

Run the build process (via custom command or Robo task):
```
php artisan chiji:release
```
Output will be generated in public/assets/dist/main.css.

Implementation Patterns

1. Integration with Laravel

Artisan Commands

Extend Laravel’s Artisan to trigger Chiji tasks:

// app/Console/Commands/ChijiBuildCommand.php
namespace App\Console\Commands;

use Chigi\Chiji\Project\Project;
use Chigi\Chiji\Util\ProjectUtil;
use Illuminate\Console\Command;

class ChijiBuildCommand extends Command {
    protected $signature = 'chiji:build';
    protected $description = 'Build front-end assets with Chiji';

    public function handle() {
        $project = ProjectUtil::getRegisteredProject('MyApp');
        foreach ($project->getSourceDirs() as $dir) {
            $project->scanAndRegisterResources($dir);
        }
        $project->buildAndRelease();
        $this->info('Chiji build completed!');
    }
}

protected $commands = [
    \App\Console\Commands\ChijiBuildCommand::class,
];

Service Provider Setup

// app/Providers/AppServiceProvider.php
public function boot() {
    $this->app->booting(function () {
        $project = new Project(__DIR__.'/../conf-file.php');
        ProjectUtil::registerProject($project);
    });
}

2. Workflow Patterns

A. Development Workflow

Watch Mode (via Robo or custom script):

// RoboFile.php
use Chigi\Chiji\Project\Project;
use Chigi\Chiji\Util\ProjectUtil;

$this->taskExec('chiji:build')->run();
$this->taskWatch('app/styles/**/*.less')->exec('chiji:build');

Annotation-Driven Processing:
- Use @require in LESS/JS to auto-load dependencies:
```
@require('vendor/jquery/dist/jquery.js');
```
- Use @release to define output paths:
```
@release('dist', 'app.css');
```

B. Production Workflow

Minification & Concatenation: Configure ProjectConfig to enable optimizations:

public function getReleaseDirs() {
    return [
        'public/assets' => [
            'dist' => [
                'concat' => true,
                'minify' => true,
            ],
        ],
    ];
}

Cache Busting: Append hashes to filenames in ProjectConfig:

public function getReleaseOptions() {
    return ['hash' => true];
}

3. Blade Integration

Render Chiji-processed assets in Blade:

// resources/views/layouts/app.blade.php
<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" href="{{ chiji_release('dist/main.css') }}">
    <script src="{{ chiji_release('dist/app.js') }}"></script>
</head>
</html>

(Requires a Blade directive or helper—see Gotchas.)

Gotchas and Tips

Pitfalls

Annotation Parsing Issues:
- Problem: @require or @release annotations in CSS/LESS may not parse due to regex limitations.
- Fix: Ensure annotations are on their own line or use /* @require */ syntax:
```
/* @require('vendor/package.css') */
```
Robo Task Conflicts:
- Problem: Chiji’s Robo tasks may conflict with Laravel Mix/Gulp.
- Fix: Use explicit task names or disable Robo in composer.json:
```
"extra": {
    "robo": {
        "disable": true
    }
}
```
Case-Sensitive Paths:
- Problem: Windows/Linux path mismatches break resource registration.
- Fix: Normalize paths in ProjectConfig:
```
public function getSourceDirs() {
    return array_map('str_replace', ['\\', '/'], ['app/scripts', 'app/styles']);
}
```

Debugging Tips

Enable Verbose Logging:

\Chigi\Chiji\Util\Logger::setLevel(\Monolog\Logger::DEBUG);

Check Registered Resources:

$project = ProjectUtil::getRegisteredProject('MyApp');
foreach ($project->getRegisteredResources() as $resource) {
    dump($resource->getFile(), $resource->getAnnotations());
}

Validate Annotations: Use the analyzeAnnotations() method to debug:

$resource = $project->getResourceByFile('app/styles/main.less');
$resource->analyzeAnnotations(); // Throws exceptions on errors

Extension Points

Custom Annotations: Extend \Chigi\Chiji\File\Annotation to add new directives:

class CustomAnnotation extends \Chigi\Chiji\File\Annotation {
    public function analyze() {
        // Custom logic for @myannotation
    }
}

Release Plugins: Implement \Chigi\Chiji\Release\PluginInterface for custom release logic (e.g., CDN uploads):

class CDNPlugin implements PluginInterface {
    public function release($resource, $road) {
        // Upload to CDN
    }
}

Blade Directives: Register a helper for chiji_release():

// app/Providers/AppServiceProvider.php
Blade::directive('chiji_release', function ($expr) {
    return "<?php echo Chigi\Chiji\Util\ReleaseUtil::dist(".$expr."); ?>";
});

Performance Quirks

Avoid Over-Scanning: Exclude non-asset directories in getSourceDirs() to speed up registration:

public function getSourceDirs() {
    return [
        'app/scripts',
        'app/styles',
        // Exclude: 'app/views', 'app/config'
    ];
}

Cache Building: Disable cache for development:

public function getBuildOptions() {
    return ['cache' => false]; // Forces rebuild on every run
}

Laravel-Specific Tips

Publish Config: Add a publishable config file for ProjectConfig:

// app/Providers/AppServiceProvider.php
if ($this->app->environment('local')) {
    $this->publishes([
        __DIR__.'/../../conf-file.php' => config_path('chiji.php'),
    ], 'chiji');
}

Queue Asset Processing: Use Laravel Queues to defer heavy builds:

// app/Console/Commands/ChijiBuildCommand.php
public function handle() {
    dispatch(new ChijiBuildJob($project));
}

Vite/Laravel Mix Compatibility: Disable Chiji for Mix-managed assets by excluding directories:

public function getSourceDirs() {
    return ['app/scripts', 'app/styles']; // Exclude 'resources/js'
}

Chiji Laravel Package