okorpheus/document-library

A package to manage a collection of PDF documents

dev-main 2026-02-03 17:21 UTC

Requires

• php: >=8.2
• blade-ui-kit/blade-heroicons: ^2.0

MIT

• Matt Young

README

A Laravel package for managing a hierarchical document library with directories, file uploads, and visibility controls.

Installation

Add the package to your Laravel application:

composer require okorpheus/document-library

The service provider is auto-discovered. Run the migrations:

php artisan migrate

Publish the configuration file:

php artisan vendor:publish --tag=documentlibrary-config

Configuration

The configuration file will be published to config/documentlibrary.php:

return [
    // Prefix for database tables
    'db_table_prefix' => env('DOCLIB_DB_TABLE_PREFIX', 'okorpheus_doclib_'),

    // Storage disk for uploaded files
    'storage_disk' => env('DOCLIB_STORAGE_DISK', 'public'),

    // Path within the disk for file storage
    'storage_path' => env('DOCLIB_STORAGE_PATH', 'document-library'),

    // Callable to determine if a user is an admin
    'admin_check' => function ($user) {
        return $user->isAdmin();
    }
];

Admin Check Configuration

The admin_check configuration option determines which users have administrative privileges in the document library. Admins can:

• View all documents and directories regardless of visibility
• Create documents and directories anywhere
• Edit and delete any document or directory

Configure this to match your application's admin logic:

// Using a method on the User model
'admin_check' => function ($user) {
    return $user->isAdmin();
}

// Using a role-based system (e.g., Spatie Permissions)
'admin_check' => function ($user) {
    return $user->hasRole('admin');
}

// Using a simple email check
'admin_check' => function ($user) {
    return in_array($user->email, ['[e-mail]']);
}

// Using a database column
'admin_check' => function ($user) {
    return $user->is_admin === true;
}

Environment Variables

You can configure the package via environment variables:

DOCLIB_DB_TABLE_PREFIX=okorpheus_doclib_
DOCLIB_STORAGE_DISK=public
DOCLIB_STORAGE_PATH=document-library

Customizing Views

To customize the document library interface, publish the views to your application:

php artisan vendor:publish --tag=documentlibrary-views

This will copy all views to resources/views/vendor/document-library/. You can then modify these files to match your application's design.

Available Views

File	Description
index.blade.php	Main document library listing page
add-directory-modal.blade.php	Modal for creating new directories
edit-directory-modal.blade.php	Modal for editing directories
upload-file-modal.blade.php	Modal for uploading files
edit-document-modal.blade.php	Modal for editing documents
components/file-list-th.blade.php	Table header component
components/file-list-td.blade.php	Table cell component

The views use Tailwind CSS and Alpine.js for styling and interactivity. Heroicons are used for icons via the blade-heroicons package.

Visibility Levels

Documents and directories support three visibility levels:

Visibility	Description
public	Visible to everyone, including guests
restricted	Visible to any authenticated user
private	Visible only to the owner and admins

Authorization

The package uses Laravel policies for authorization:

Documents

• View: Based on visibility level and ownership
• Create: Authenticated users can create in public directories or directories they own
• Update: Owner or admin only
• Delete: Owner or admin only

Directories

• View: Based on visibility level and ownership
• Create: Authenticated users can create in public directories or directories they own
• Update: Owner or admin only
• Delete: Owner or admin only (directory must be empty)

Routes

All routes are prefixed with /document-library:

Method	URI	Name	Description
GET	/	document-library.index	List root directories and documents
GET	/{directory}	document-library.directory	List contents of a directory
POST	/directory	document-library.directory.store	Create a new directory
PATCH	/directory/{directory}	document-library.directory.update	Update a directory
DELETE	/directory/{directory}	document-library.directory.destroy	Delete a directory
POST	/	document-library.file.store	Upload a new file
PATCH	/file/{document}	document-library.document.update	Update a document
DELETE	/file/{document}	document-library.document.destroy	Delete a document

Usage

Navigate to /document-library to access the document library interface. Authenticated users can:

• Create directories and upload files
• Edit and delete their own content
• View content based on visibility settings

Admins have full access to all content.

Requirements

• PHP 8.2+
• Laravel 11+
• blade-ui-kit/blade-heroicons (installed as a dependency)

License

MIT