Filesbundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Install Dependencies

   composer require afornerot/bnine-filesbundle oneup/uploader-bundle
   

2. Configure Required Libraries Add to your app.js (Webpack Encore) or include via CDN in your base template:

   <!-- CDN Example -->
   <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.0/css/all.min.css">
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/dropzone@6/dist/dropzone.min.css">
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/dropzone-bootstrap@1/dist/dropzone-bootstrap.min.css">
   <script src="https://cdn.jsdelivr.net/npm/jquery@3/dist/jquery.min.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/dropzone@6/dist/dropzone.min.js"></script>
   

3. Enable the Bundle Add to config/bundles.php (if not using Symfony Flex):

   Bnine\FilesBundle\BnineFilesBundle::class => ['all' => true],
   

4. Configure Routing Add to config/routes.yaml:

   bninefilesbundle:
       resource: '@BnineFilesBundle/config/routes.yaml'
       prefix: '/bninefiles'
   

5. Configure OneupUploader Add to config/packages/oneup_uploader.yaml:

   oneup_uploader:
       mappings:
           bninefile:
               frontend: dropzone
   

6. Initialize File Container In your controller, initialize the file container after persisting an entity:

   $fileService->init('project', $project->getId());
   

7. Display File Browser in Template Insert the Twig snippet where needed:

   {{ render(path("bninefiles_files", {domain: 'project', id: project.id, editable: 1})) }}
   

Implementation Patterns

Workflows

1. Entity-Based File Management

   • Use the FileService to initialize a file container for any entity after saving it to the database.
   • Example: init('project', $projectId) creates a directory structure for a project.

2. Secure File Uploads

   • Integrate with OneupUploaderBundle for handling file uploads.
   • Use the editable: 1 parameter in Twig to enable uploads via Dropzone.js.

3. Access Control

   • Implement a custom FileVoter to define permissions for viewing, editing, and deleting files.
   • Example: Restrict file access to project owners or admins.

4. Template Integration

   • Use the render Twig function to embed the file browser in any template.
   • Toggle editable parameter to switch between read-only and full-featured modes.

5. Breadcrumbs and Navigation

   • The bundle provides Bootstrap/FontAwesome-ready templates for intuitive navigation.
   • No additional setup required for basic use.

Integration Tips

• Customize UI: Override the bundle’s Twig templates in your project’s templates/bNineFiles/ directory.
• Extend Functionality: Use the abstract FileVoter as a base for custom security logic.
• Batch Operations: Leverage the FileService methods to manage files programmatically (e.g., delete all files for a project).
• Frontend Enhancements: Extend Dropzone.js configuration via JavaScript for custom upload behaviors.

Gotchas and Tips

Pitfalls

1. Fixed Upload Path

   • The upload directory must be %kernel.project_dir%/uploads. Changing this will break the bundle.
   • Workaround: Use symbolic links if you need a different path.

2. Missing Dependencies

   • Forgetting to include jQuery, Bootstrap, FontAwesome, or Dropzone.js will break the frontend.
   • Tip: Use Webpack Encore for better dependency management.

3. Security Misconfigurations

   • Without a custom FileVoter, all users will have full access to files.
   • Tip: Always implement canView, canEdit, and canDelete methods in your voter.

4. Template Overrides

   • Overriding Twig templates requires naming them exactly (e.g., files/index.html.twig).
   • Tip: Clear the cache after overriding templates.

5. Entity Initialization

   • Forgetting to call init() on an entity will result in a missing directory.
   • Tip: Add a lifecycle callback or event listener to auto-initialize.

Debugging

• 404 Errors: Verify routes are imported correctly in config/routes.yaml.
• JavaScript Errors: Check the browser console for missing libraries or conflicts.
• Permission Denied: Ensure your FileVoter is properly registered and configured.

Extension Points

1. Custom File Types

   • Extend the FileService to support additional file operations (e.g., file previews, metadata extraction).

2. Advanced Voters

   • Add logic to your FileVoter for domain-specific permissions (e.g., role-based access).

3. Event Listeners

   • Listen to files.post_upload or files.post_delete events for post-processing.

4. API Integration

   • Use the FileService methods in API controllers to manage files via endpoints.

Configuration Quirks

• OneupUploader Mapping: Ensure the frontend: dropzone mapping is correctly set in oneup_uploader.yaml.
• Twig Paths: If using custom templates, explicitly add the bundle’s Twig paths in twig.yaml.
• Caching: Clear the Symfony cache after making configuration changes.

Pro Tips

• Batch Deletion: Use FileService::deleteAll() to clean up files for deleted entities.
• File Previews: Extend the template to show thumbnails for images.
• Audit Logs: Log file operations (upload/delete) for compliance or debugging.