PHPackages dynamia-tools/buckie - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. dynamia-tools/buckie ActiveProject[API Development](/categories/api) dynamia-tools/buckie ==================== Buckie PHP — filesystem-native file server with a minimal S3-style REST API. Standalone application. 1.0.0(2mo ago)01MITPHP >=8.0 Since May 25Compare [ Source](https://github.com/dynamiatools/buckie-php)[ Packagist](https://packagist.org/packages/dynamia-tools/buckie)[ RSS](/packages/dynamia-tools-buckie/feed)WikiDiscussions Synced 3w ago READMEChangelog (1)Dependencies (1)Versions (2)Used By (0) [![Packagist Version](https://camo.githubusercontent.com/4439c6963c368c05d2f3b2bacfe6d27e3d32f277f2131b93b9fd80eb3c3ff36a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f64796e616d69612d746f6f6c732f6275636b6965)](https://camo.githubusercontent.com/4439c6963c368c05d2f3b2bacfe6d27e3d32f277f2131b93b9fd80eb3c3ff36a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f64796e616d69612d746f6f6c732f6275636b6965)[![Packagist Downloads](https://camo.githubusercontent.com/8243e3ead26b86d29e27278ef14c19fd47f013b777c27794b229e537372a5e0f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f64796e616d69612d746f6f6c732f6275636b6965)](https://camo.githubusercontent.com/8243e3ead26b86d29e27278ef14c19fd47f013b777c27794b229e537372a5e0f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f64796e616d69612d746f6f6c732f6275636b6965)[![PHP Version](https://camo.githubusercontent.com/ec43904de1fedf19269a0775ca6f40f4bbc0e049f68caef1bb96cefbafe56d02/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f64796e616d69612d746f6f6c732f6275636b6965)](https://camo.githubusercontent.com/ec43904de1fedf19269a0775ca6f40f4bbc0e049f68caef1bb96cefbafe56d02/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f64796e616d69612d746f6f6c732f6275636b6965)[![License](https://camo.githubusercontent.com/f49713f94d2060b4a6ee7fa5f7cca9cf691963a6663ff6149d589e29ccf3576c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f64796e616d69612d746f6f6c732f6275636b6965)](https://camo.githubusercontent.com/f49713f94d2060b4a6ee7fa5f7cca9cf691963a6663ff6149d589e29ccf3576c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f64796e616d69612d746f6f6c732f6275636b6965) Buckie PHP ========== [](#buckie-php) PHP 8+ implementation of Buckie — a filesystem-native file server with a minimal S3-style REST API. Designed for **shared hosting and standard PHP environments**: no framework, no database, no message broker. Just PHP and a disk. > **Standalone application** — Buckie PHP runs as a self-contained CLI tool and/or HTTP server. It is **not** a reusable library to be required inside another project. --- Usage modes ----------- [](#usage-modes) ModeHowDescription**CLI**`php bin/buckie `Manage buckets, identities, files and permissions from the terminal**HTTP server (dev)**`php bin/buckie serve`Starts PHP's built-in server — useful for local development**HTTP server (prod)**Apache / Nginx / FrankenPHPDeploy `public/index.php` under any standard PHP web server--- Features -------- [](#features) - **Zero external dependencies** — only PHP 8.0+ and standard extensions (GD, finfo) - **Single config file** — all state lives in `.buckie/config.json` - **On-the-fly thumbnails** — GD (default) or Imagick; automatic caching - **Same REST API as the Node.js implementation** - **Same CLI contract as the Node.js implementation** - **Local FS only** — no SFTP; ideal for shared hosting - **Authentication** via `X-Buckie-Identity`/`X-Buckie-Secret` headers or HTTP Basic Auth - **Secret hashing** with `password_hash(PASSWORD_DEFAULT)` (bcrypt) — cross-compatible with the Node.js implementation - **Staging + atomic rename** for uploads — no partial reads --- Requirements ------------ [](#requirements) RequirementMinimumPHP**8.0**Composer2+GD extensionany recent version (or Imagick)finfo extensionbundled with PHP 8--- Installation ------------ [](#installation) ### Option A — create-project (recommended) [](#option-a--create-project-recommended) ``` composer create-project dynamia-tools/buckie buckie-php cd buckie-php ``` This installs Buckie as a standalone application in the `buckie-php/` directory. ### Option B — clone + install [](#option-b--clone--install) ``` git clone https://github.com/dynamia-tools/buckie buckie-php cd buckie-php/buckie-php composer install ``` ### Make the CLI available globally [](#make-the-cli-available-globally) ``` # Link the binary to a directory in your $PATH ln -s "$(pwd)/bin/buckie" ~/.local/bin/buckie chmod +x ~/.local/bin/buckie ``` --- Quick Start ----------- [](#quick-start) ### As a CLI tool [](#as-a-cli-tool) All management operations (buckets, identities, permissions, files) are handled through the `buckie` CLI: ``` # Create a bucket php bin/buckie create bucket documents /var/storage/documents # Create an identity php bin/buckie create identity erp-prod my-secret-password # Grant permissions php bin/buckie grant erp-prod documents --read --write --delete --prefix /tenant-a/ # List all buckets php bin/buckie list buckets # Upload a file directly from the terminal php bin/buckie upload documents tenant-a/invoice.pdf ./invoice.pdf ``` Run `php bin/buckie --help` to see all available commands. ### As an HTTP server (development) [](#as-an-http-server-development) ``` php bin/buckie serve --host 0.0.0.0 --port 8080 ``` ### As an HTTP server (production) [](#as-an-http-server-production) Deploy the `public/` directory under Apache, Nginx or FrankenPHP (see [Production Deployment](#production-deployment) below). --- Production Deployment --------------------- [](#production-deployment) Buckie PHP is deployed like any standard PHP application. Set the document root to the `public/` directory. ### Apache [](#apache) Make sure `mod_rewrite` is enabled. The `public/.htaccess` file already contains the required configuration. ``` ServerName storage.example.com DocumentRoot /var/www/buckie/public AllowOverride All Require all granted ``` ### Nginx [](#nginx) ``` server { listen 80; server_name storage.example.com; root /var/www/buckie/public; index index.php; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { fastcgi_pass unix:/run/php/php8.0-fpm.sock; fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name; include fastcgi_params; } } ``` ### FrankenPHP [](#frankenphp) ``` frankenphp php-server --root public/ ``` ### Docker (pruebas locales con Apache) [](#docker-pruebas-locales-con-apache) El repositorio incluye un `Dockerfile` y un `docker-compose.yml` listos para pruebas locales. ``` # 1. Construir la imagen e iniciar el contenedor docker compose up --build -d # 2. Verificar que el servicio está activo curl http://localhost:8080/health # 3. Crear un bucket (la ruta debe existir DENTRO del contenedor) docker exec buckie-php php bin/buckie create bucket docs /var/buckie-storage/docs # 4. Crear una identidad docker exec buckie-php php bin/buckie create identity dev-user secret123 # 5. Otorgar permisos docker exec buckie-php php bin/buckie grant dev-user docs --read --write --delete # 6. Subir un archivo de prueba curl -X PUT http://localhost:8080/docs/hello.txt \ -H "X-Buckie-Identity: dev-user" \ -H "X-Buckie-Secret: secret123" \ -H "Content-Type: text/plain" \ --data-binary "Hola desde Buckie PHP 🚀" # 7. Descargar el archivo curl http://localhost:8080/docs/hello.txt \ -H "X-Buckie-Identity: dev-user" \ -H "X-Buckie-Secret: secret123" # 8. Detener el contenedor docker compose down ``` Los datos persisten entre reinicios en `./docker-data/`: ``` docker-data/ ├── buckie/ ← config.json, logs/, cache/ └── storage/ ← archivos subidos ``` **Variables de entorno disponibles** (configurables en `docker-compose.yml`): VariableDefault en DockerDescripción`BUCKIE_DATA_DIR``/var/buckie-data`Config, logs y caché`BUCKIE_STORAGE_DIR``/var/buckie-storage`Almacenamiento de archivos`BUCKIE_LOG_LEVEL``debug`Nivel de log### Environment Variables [](#environment-variables) VariableDefaultDescription`BUCKIE_DATA_DIR``/.buckie`Data directory (config, logs, cache)`BUCKIE_HOST``0.0.0.0`Bind host (development server only)`BUCKIE_PORT``8080`Bind port (development server only)`BUCKIE_LOG_LEVEL``info`Log level--- CLI Reference ------------- [](#cli-reference) ``` # Development server (not for production) php bin/buckie serve [--host ] [--port ] [--data-dir ] # Buckets php bin/buckie create bucket php bin/buckie list buckets php bin/buckie remove bucket # Identities php bin/buckie create identity php bin/buckie list identities php bin/buckie remove identity # Permissions php bin/buckie grant --read --write --delete [--prefix ] php bin/buckie revoke # Files php bin/buckie list files [path] php bin/buckie upload php bin/buckie copy # Provisioning (create identity + secret + grant in one step) php bin/buckie provision [--identity ] [--prefix ] [--read] [--write] [--delete] # Shell tab completion eval "$(php bin/buckie completion bash)" # Bash — add to ~/.bashrc eval "$(php bin/buckie completion zsh)" # Zsh — add to ~/.zshrc php bin/buckie completion fish > ~/.config/fish/completions/buckie.fish ``` --- REST API -------- [](#rest-api) All requests (except `GET /health`) require authentication via `X-Buckie-Identity` + `X-Buckie-Secret` headers, or HTTP Basic Auth. ### Health check [](#health-check) ``` GET /health ``` ### Download a file [](#download-a-file) ``` GET /:bucket/:key X-Buckie-Identity: erp-prod X-Buckie-Secret: my-secret-password ``` ### Download a thumbnail (on-the-fly resize) [](#download-a-thumbnail-on-the-fly-resize) ``` GET /:bucket/:key?w=300&h=300&fit=cover&format=webp ``` Supported query parameters: `w` (width), `h` (height), `fit` (`cover` | `contain` | `fill`), `format` (`webp` | `jpeg` | `png`). ### List a directory [](#list-a-directory) ``` GET /:bucket/:path/ ``` ### List bucket contents (paginated) [](#list-bucket-contents-paginated) ``` GET /:bucket?limit=100&cursor=... ``` ### Upload a file [](#upload-a-file) ``` PUT /:bucket/:key Content-Type: application/octet-stream [body: file stream] ``` ### Delete a file [](#delete-a-file) ``` DELETE /:bucket/:key ``` --- curl Examples ------------- [](#curl-examples) ``` # Health check curl http://localhost:8080/health # Upload a file curl -X PUT http://localhost:8080/documents/tenant-a/invoice.pdf \ -H "X-Buckie-Identity: erp-prod" \ -H "X-Buckie-Secret: my-secret-password" \ -H "Content-Type: application/octet-stream" \ --data-binary @invoice.pdf # Upload using HTTP Basic Auth curl -X PUT http://localhost:8080/documents/tenant-a/report.xlsx \ -u "erp-prod:my-secret-password" \ -H "Content-Type: application/octet-stream" \ --data-binary @report.xlsx # Download a file curl http://localhost:8080/documents/tenant-a/invoice.pdf \ -H "X-Buckie-Identity: erp-prod" \ -H "X-Buckie-Secret: my-secret-password" \ -o invoice.pdf # Download a thumbnail curl "http://localhost:8080/documents/tenant-a/photo.jpg?w=300&h=300&fit=cover&format=webp" \ -H "X-Buckie-Identity: erp-prod" \ -H "X-Buckie-Secret: my-secret-password" \ -o thumbnail.webp # List a directory curl http://localhost:8080/documents/tenant-a/ \ -H "X-Buckie-Identity: erp-prod" \ -H "X-Buckie-Secret: my-secret-password" # List bucket contents (paginated) curl "http://localhost:8080/documents?limit=50" \ -H "X-Buckie-Identity: erp-prod" \ -H "X-Buckie-Secret: my-secret-password" # Delete a file curl -X DELETE http://localhost:8080/documents/tenant-a/invoice.pdf \ -H "X-Buckie-Identity: erp-prod" \ -H "X-Buckie-Secret: my-secret-password" ``` --- Project Structure ----------------- [](#project-structure) ``` . ├── bin/ │ └── buckie ← CLI entry point (executable) ├── public/ │ ├── index.php ← HTTP entry point (framework-free router) │ └── .htaccess ← Apache mod_rewrite configuration ├── src/ │ ├── Auth/ │ │ └── IdentityService.php ← Identity CRUD, hashing, permission check │ ├── Config/ │ │ └── ConfigService.php ← config.json read/write, data directory paths │ ├── Errors/ │ │ └── BuckieException.php ← Typed exceptions with HTTP status │ ├── Http/ │ │ └── Router.php ← HTTP routing and request handling │ ├── Logging/ │ │ └── OperationalLogger.php ← JSONL access and error logs │ ├── Storage/ │ │ ├── BucketService.php ← Bucket CRUD, path traversal protection │ │ └── LocalStorageService.php ← Upload/download/delete/list operations │ └── Thumbnail/ │ └── ThumbnailService.php ← On-the-fly thumbnails via GD/Imagick └── composer.json ``` --- Data Directory Structure ------------------------ [](#data-directory-structure) ``` .buckie/ ├── config.json # Buckets, identities and grants ├── logs/ │ ├── access.log.jsonl │ └── error.log.jsonl └── cache/ # Reserved for future use ``` Each local bucket also maintains an internal directory: ``` /path/to/bucket/ ├── tenant-a/ │ ├── invoice.pdf │ └── 300x300/ │ └── photo.webp ← Cached thumbnail └── .buckie/ └── staging/ ← Temporary upload staging area ``` --- Differences from the Node.js Implementation ------------------------------------------- [](#differences-from-the-nodejs-implementation) FeatureNode.jsPHPStorage backendsLocal FS + SFTP**Local FS only**Secret hashingbcrypt (`bcrypt` npm)`password_hash` / bcryptHash interoperability✅ Compatible✅ CompatibleHTTP serverFastifyPHP built-in / Apache / Nginx / FrankenPHPFile streamingNode.js streams`fpassthru`ThumbnailsSharpGD / ImagickProgrammatic APIFull SDKNot available--- Security -------- [](#security) - **Private by default** — every request requires authentication; only `/health` is public - **bcrypt password hashing** — secrets are never stored in plain text; hashes are cross-compatible with the Node.js implementation - **Prefix-based authorization** — access can be restricted by bucket and path prefix - **Path traversal protection** — canonical path validation on every request - **Staging + atomic commit** — uploads are written to staging first to prevent partial reads --- Related Implementations ----------------------- [](#related-implementations) ImplementationRepositoryBest for**Buckie Node.js**[github.com/dynamiatools/buckie-node-js](https://github.com/dynamiatools/buckie-node-js)High-throughput servers — includes SFTP storage backend and full programmatic TypeScript SDK--- License ------- [](#license) MIT © Dynamia Soluciones IT SAS ### Health Score 34 — LowBetter than 75% of packages Maintenance88 Actively maintained with recent releases Popularity1 Limited adoption so far Community2 Small or concentrated contributor base Maturity38 Early-stage or recently created project How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 61d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/4ba28b553c6a20ec47620ea40e970f420259268dcc057450223fcfe9967dc262?d=identicon)[dynamia-tools](/maintainers/dynamia-tools) ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/dynamia-tools-buckie/health.svg) ``` [![Health](https://phpackages.com/badges/dynamia-tools-buckie/health.svg)](https://phpackages.com/packages/dynamia-tools-buckie) ``` ### Alternatives [exsyst/swagger A php library to manipulate Swagger specifications 35916.4M7](/packages/exsyst-swagger)[hubspot/api-client Hubspot API client 24016.2M20](/packages/hubspot-api-client)[pocketmine/bedrock-protocol An implementation of the Minecraft: Bedrock Edition protocol in PHP 172445.0k18](/packages/pocketmine-bedrock-protocol)[botman/driver-telegram Telegram driver for BotMan 93459.5k6](/packages/botman-driver-telegram) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)