Change Log Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require mohkoma/change-log
   php artisan vendor:publish --provider="Mohkoma\ChangeLog\ChangeLogServiceProvider"
   

   • Accept the config and views prompts.

2. First Use Case:

   • Access /dev/changelog/create to add your first changelog entry via the provided form.
   • Verify entries in /dev/changelog (list view) or /dev/changelog/json (raw JSON).

3. Config Quickstart: Update config/changelog.php to define your project’s release versions and storage disk:

   'versions' => [
       '1.0.0' => '2020-10-01',
       '2.0.0' => '2024-01-01', // Add future releases
   ],
   'storage_disk' => 'local', // Use 'local' for filesystem storage
   

Implementation Patterns

Core Workflows

1. Versioned Changelog Management:

   • Use the form at /dev/changelog/create to log changes per release (e.g., bug fixes, features).
   • Associate entries with versions in config/changelog.php to auto-group them in the list view.

2. Storage Integration:

   • Leverage the storage_disk config to store JSON files in a custom disk (e.g., local, s3). Example:

     'storage_disk' => 's3',
     'directory_name' => 'public/changelogs',
     

   • Publish views to customize the HTML output (e.g., modify resources/views/vendor/changelog/list.blade.php).

3. API Access:

   • Fetch changelogs programmatically via the JSON endpoint:

     $logs = json_decode(file_get_contents(url('/dev/changelog/json')), true);
     

   • Useful for CI/CD pipelines or frontend integration (e.g., React/Vue apps).

4. Middleware Customization:

   • Restrict access by updating the middleware config:

     'middleware' => [
         'read'  => ['web', 'auth:support'], // Example: Limit to 'support' role
         'create' => ['web', 'auth:admin'],  // Separate middleware for creation
     ],
     

Integration Tips

• Laravel Events: Trigger changelog updates on deployments via Artisan::call('changelog:create') in a Deploying listener.
• Git Hooks: Auto-generate changelog entries by parsing commit messages (e.g., using git log --oneline).
• Frontend Display: Embed the JSON endpoint in your app’s footer or release notes page:

  fetch('/dev/changelog/json')
    .then(res => res.json())
    .then(data => renderChangelog(data));
  

Gotchas and Tips

Pitfalls

1. Storage Disk Misconfiguration:

   • If storage_disk isn’t configured, files may save to an unexpected location (default: storage/app/changelog).
   • Fix: Verify the disk exists in config/filesystems.php or use 'local'.

2. Version Ordering:

   • The package sorts versions by config/changelog.php order (oldest first). Add new versions at the end to maintain chronological order.
   • Tip: Use semantic versioning (e.g., 1.0.0, 2.0.0) for clarity.

3. Form Validation:

   • The form lacks CSRF protection by default. Ensure your middleware includes web (which includes @method and @csrf).
   • Fix: Add @csrf to the published form view.

4. JSON Merge Issues:

   • Merging JSON files may fail if entries lack unique IDs. The package assumes entries have a id field.
   • Tip: Include id: Date.now() or id: uuid() in your form data.

Debugging

• Missing Routes: Run php artisan route:list to confirm /dev/changelog* routes exist.
• File Permissions: Ensure the storage directory is writable:

  chmod -R 755 storage/app/changelog
  

• View Overrides: Clear cached views after publishing:

  php artisan view:clear
  

Extension Points

1. Custom Fields:

   • Extend the form by modifying the published view (resources/views/vendor/changelog/create.blade.php) or override the Changelog model (if available).

2. API Enhancements:

   • Add filters to the JSON endpoint by extending the JsonController (located in vendor/mohkoma/change-log/src/Http/Controllers/JsonController.php). Override it in your app:

     // app/Http/Controllers/ChangelogJsonController.php
     class ChangelogJsonController extends \Mohkoma\ChangeLog\Http\Controllers\JsonController {
         public function index() {
             // Add custom logic (e.g., filter by version)
             return parent::index();
         }
     }
     

   • Update routes in routes/web.php:

     Route::get('/dev/changelog/json', [\App\Http\Controllers\ChangelogJsonController::class, 'index']);
     

3. Localization:

   • Translate the form/views by publishing and extending the language files (e.g., resources/lang/en/changelog.php).