PHPackages owlfice/citadel - 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. [Testing & Quality](/categories/testing) 4. / 5. owlfice/citadel ActiveProject[Testing & Quality](/categories/testing) owlfice/citadel =============== Citadel - A production-ready Laravel backend boilerplate with OAuth2, permissions, media management, full-text search capabilities, and interactive admin commands. v1.0.0(11mo ago)011MITPHPPHP ^8.2CI passing Since Jul 30Pushed 11mo agoCompare [ Source](https://github.com/AshrafAmir96/citadel)[ Packagist](https://packagist.org/packages/owlfice/citadel)[ Docs](https://github.com/AshrafAmir96/citadel)[ RSS](/packages/owlfice-citadel/feed)WikiDiscussions main Synced today READMEChangelog (1)Dependencies (19)Versions (2)Used By (0) Citadel - Laravel Backend Boilerplate ===================================== [](#citadel---laravel-backend-boilerplate) [![Laravel Logo](https://raw.githubusercontent.com/laravel/art/master/logo-lockup/5%20SVG/2%20CMYK/1%20Full%20Color/laravel-logolockup-cmyk-red.svg)](https://raw.githubusercontent.com/laravel/art/master/logo-lockup/5%20SVG/2%20CMYK/1%20Full%20Color/laravel-logolockup-cmyk-red.svg) [![Build Status](https://github.com/laravel/framework/workflows/tests/badge.svg)](https://github.com/laravel/framework/actions)[![Total Downloads](https://camo.githubusercontent.com/b0a7ee2f3f0208712ecb1081b9d6fcf05045c10cd6f345abcb924f5512c0d346/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6c61726176656c2f6672616d65776f726b)](https://packagist.org/packages/laravel/framework)[![Latest Stable Version](https://camo.githubusercontent.com/9e6071b5dd1a4a3bcabe3cca9d97a447d030caeb940f2adbd18699bc0b326702/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6c61726176656c2f6672616d65776f726b)](https://packagist.org/packages/laravel/framework)[![License](https://camo.githubusercontent.com/4a64c31c71966d152c876eea1f35e85fbd33d57ddf5754260a41f053aa72c5b2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6c61726176656c2f6672616d65776f726b)](https://packagist.org/packages/laravel/framework) **πŸš€ Production-Ready Laravel Backend Boilerplate** Built with Laravel 12, PHP 8.2+, and modern development practices --- 🎯 About Citadel --------------- [](#-about-citadel) Citadel is a **production-ready Laravel backend boilerplate** designed to accelerate your web application development. Built with **Laravel 12** and modern **PHP 8.2+**, it provides a robust foundation with enterprise-grade features including OAuth2 authentication, role-based permissions, media management, and full-text search capabilities. ### ✨ Why Choose Citadel? [](#-why-choose-citadel) - ⚑ **Fast Setup** - Get your API up and running in minutes - πŸ—οΈ **Production Ready** - Built with scalability and security in mind - πŸ”’ **Enterprise Security** - OAuth2, RBAC, and security best practices - πŸ§ͺ **Test Driven** - Comprehensive testing suite with Pest PHP - 🐳 **Docker Ready** - Complete containerization for development and deployment - πŸš€ **CI/CD Included** - GitLab pipeline for automated testing and deployment - πŸ“š **Well Documented** - Extensive documentation and examples πŸš€ Quick Start ------------- [](#-quick-start) Get Citadel running in 5 minutes! See [QUICKSTART.md](QUICKSTART.md) for detailed instructions. πŸ“Š Version Information --------------------- [](#-version-information) Current version: `{{ app_version() }}` - **Semantic Versioning**: Automated version management with CI/CD - **GitLab CI/CD**: See [SEMANTIC\_VERSIONING.md](SEMANTIC_VERSIONING.md) - **GitHub Actions**: See [GITHUB\_ACTIONS.md](GITHUB_ACTIONS.md) - **Version API**: `GET /api/version` for version information - **Release Notes**: See [CHANGELOG.md](CHANGELOG.md) for version history - **CI/CD Switcher**: Use `scripts/ci-switch.sh` to switch between platforms πŸ› οΈ Development Tools -------------------- [](#️-development-tools) ### Code Quality [](#code-quality) - **PHP CS Fixer (Pint)**: Automatic code formatting - **PHPStan with Larastan**: Static analysis for Laravel - **Pest**: Modern PHP testing framework - **Pre-commit hooks**: Automated quality checks ### Available Scripts [](#available-scripts) ``` # Code formatting composer run pint # Static analysis composer run analyse # Run tests composer run test # All quality checks composer run quality # Development server with hot reload composer run dev ``` ✨ Features ---------- [](#-features) ### Option 1: Docker (Recommended) [](#option-1-docker-recommended) ``` git clone citadel cd citadel docker-compose up -d # Create your first super admin user docker-compose exec app php artisan citadel:create-super-admin \ --email=admin@yourcompany.com \ --password=SecurePassword123! \ --name="Admin User" ``` **🌐 Access:** ### Option 2: Traditional Setup [](#option-2-traditional-setup) ``` git clone citadel cd citadel composer install && npm install cp .env.example .env && php artisan key:generate php artisan migrate && php artisan passport:install # Create your first super admin user php artisan citadel:create-super-admin \ --email=admin@yourcompany.com \ --password=SecurePassword123! \ --name="Admin User" composer run dev ``` **🌐 Access:** ### Option 3: Laravel Sail [](#option-3-laravel-sail) ``` git clone citadel cd citadel ./vendor/bin/sail up -d # Create your first super admin user ./vendor/bin/sail artisan citadel:create-super-admin \ --email=admin@yourcompany.com \ --password=SecurePassword123! \ --name="Admin User" ``` **🌐 Access:** ✨ Key Features -------------- [](#-key-features) ### πŸ” Authentication & Authorization [](#-authentication--authorization) - **Laravel Passport OAuth2** - Complete OAuth2 server implementation - **Role-Based Access Control** - Spatie Laravel Permission with dot notation (`users.*`, `media.*`) - **Super Admin Management** - Dedicated command for creating super admin users - **JWT Token Authentication** - Secure API authentication - **Permission Helper Functions** - Wildcard-aware permission checking #### 🏰 Super Admin Creation Command [](#-super-admin-creation-command) Citadel includes a powerful interactive command for creating super admin users: ``` # Interactive mode with confirmation prompts php artisan citadel:create-super-admin # Direct mode with parameters php artisan citadel:create-super-admin \ --email=admin@example.com \ --password=SecurePassword123! \ --name="Super Admin" # Docker environment docker-compose exec app php artisan citadel:create-super-admin \ --email=admin@example.com \ --password=SecurePassword123! \ --name="Super Admin" ``` **Features:** - βœ… **Interactive UI** - Beautiful table formatting with confirmation prompts - βœ… **Validation** - Email uniqueness and password strength validation - βœ… **Role Assignment** - Automatically assigns "Super Admin" role with all permissions - βœ… **Success Feedback** - Clear confirmation with user details and next steps - βœ… **Docker Compatible** - Works seamlessly in containerized environments ### 🎯 Modern API Design [](#-modern-api-design) - **Query Builder Integration** - Spatie Laravel Query Builder for flexible API queries - **Advanced Filtering** - `?filter[name]=john&sort=-created_at&include=roles` - **Field Selection** - `?fields[users]=id,name,email` for optimized responses - **Auto-Generated Docs** - Scramble for automatic OpenAPI documentation - **Consistent Responses** - Standardized JSON API response format ### πŸ“ Media & Content Management [](#-media--content-management) - **File Upload System** - Spatie Laravel Medialibrary integration - **Image Processing** - Automatic optimization and thumbnail generation - **Full-Text Search** - Laravel Scout with multiple drivers - **Multiple Storage** - Local, S3, and cloud storage support ### πŸ§ͺ Developer Experience [](#-developer-experience) - **Pest PHP Testing** - Modern testing framework with beautiful syntax - **Docker Development** - One-command environment setup - **Code Quality Tools** - Laravel Pint, PHPStan integration - **Hot Module Replacement** - Fast development with Vite - **Redis Integration** - High-performance caching and sessions πŸ“¦ Key Technologies ------------------ [](#-key-technologies) ComponentTechnologyPurpose**Framework**Laravel 12Backend foundation**Authentication**Laravel PassportOAuth2 server**Permissions**Spatie PermissionRole-based access control**Media**Spatie MedialibraryFile management**Search**Laravel ScoutFull-text search**API Queries**Spatie Query BuilderFlexible API filtering**Testing**Pest PHPModern testing framework**Frontend**Tailwind CSS + ViteModern UI development**Cache/Queue**RedisHigh-performance data store**Database**MySQL/PostgreSQL/SQLiteFlexible database supportπŸ—οΈ Project Structure -------------------- [](#️-project-structure) ### API Controllers (Organized) [](#api-controllers-organized) ``` app/Http/Controllers/Api/ β”œβ”€β”€ AuthController.php # Authentication endpoints β”œβ”€β”€ UserController.php # User management with QueryBuilder β”œβ”€β”€ MediaController.php # File upload and management β”œβ”€β”€ SearchController.php # Full-text search functionality └── ApiDocumentationController.php # API documentation ``` ### Artisan Commands [](#artisan-commands) ``` app/Console/Commands/ β”œβ”€β”€ SuperAdminCreation.php # Interactive super admin creation command └── GetRoleList.php # Role management and statistics command ``` ### Documentation Structure [](#documentation-structure) ``` β”œβ”€β”€ README.md # Project overview and quick start β”œβ”€β”€ QUICKSTART.md # 5-minute setup guide β”œβ”€β”€ DOCKER.md # Docker development guide β”œβ”€β”€ COMMANDS.md # Artisan commands reference β”œβ”€β”€ DEPLOYMENT.md # Production deployment guide β”œβ”€β”€ SEMANTIC_VERSIONING.md # Semantic versioning with GitLab CI/CD β”œβ”€β”€ GITHUB_ACTIONS.md # GitHub Actions CI/CD setup β”œβ”€β”€ CHANGELOG.md # Version history and changes └── CONTRIBUTING.md # Contribution guidelines ``` ### Configuration System [](#configuration-system) - **`config/citadel.php`** - Centralized configuration - **`app/helpers.php`** - Helper functions with autoloading - **`.env.citadel.example`** - Environment variable examples πŸš€ CI/CD Integration ------------------- [](#-cicd-integration) Citadel supports both **GitLab CI/CD** and **GitHub Actions** with identical functionality: ### 🦊 GitLab CI/CD [](#-gitlab-cicd) - **Configuration**: `.gitlab-ci.yml` - **Semantic Release**: `.releaserc.json` - **Documentation**: [SEMANTIC\_VERSIONING.md](SEMANTIC_VERSIONING.md) - **Features**: Automated testing, security scans, semantic versioning, multi-environment deployment ### πŸ™ GitHub Actions [](#-github-actions) - **Configuration**: `.github/workflows/ci-cd.yml` - **Semantic Release**: `.releaserc.github.json` - **Documentation**: [GITHUB\_ACTIONS.md](GITHUB_ACTIONS.md) - **Features**: Automated testing, CodeQL security, semantic versioning, environment protection ### πŸ”„ Platform Switching [](#-platform-switching) ``` # Switch to GitLab CI/CD ./scripts/ci-switch.sh gitlab # Switch to GitHub Actions ./scripts/ci-switch.sh github # Check current status ./scripts/ci-switch.sh status ``` ### 🏷️ Semantic Versioning [](#️-semantic-versioning) Both platforms use conventional commits for automatic version management: ``` feat: add new feature # Minor version bump (1.0.0 β†’ 1.1.0) fix: resolve bug # Patch version bump (1.0.0 β†’ 1.0.1) feat!: breaking change # Major version bump (1.0.0 β†’ 2.0.0) ``` πŸ”§ Available Commands -------------------- [](#-available-commands) ### Super Admin Management [](#super-admin-management) ``` # Create a new super admin user (interactive) php artisan citadel:create-super-admin # Create super admin with parameters php artisan citadel:create-super-admin --email=admin@example.com --password=SecurePass123! --name="Admin" # View all available citadel commands php artisan list citadel ``` ### Development Commands [](#development-commands) ``` # Generate API documentation php artisan scramble:generate # Clear all caches php artisan optimize:clear # Run tests ./vendor/bin/pest # Run code analysis ./vendor/bin/phpstan analyse ``` 🀝 Contributing -------------- [](#-contributing) 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add some amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request πŸ“„ License --------- [](#-license) This project is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT). πŸ™ Acknowledgments ----------------- [](#-acknowledgments) - [Laravel Framework](https://laravel.com) - The web artisans framework - [Spatie](https://spatie.be) - Amazing Laravel packages - [Pest PHP](https://pestphp.com) - Modern testing framework - [Tailwind CSS](https://tailwindcss.com) - Utility-first CSS framework πŸ™ Acknowledgments ----------------- [](#-acknowledgments-1) - [Laravel Framework](https://laravel.com) - The web artisans framework - [Spatie](https://spatie.be) - Amazing Laravel packages - [Pest PHP](https://pestphp.com) - Modern testing framework - [Tailwind CSS](https://tailwindcss.com) - Utility-first CSS framework ### Health Score 30 β€” LowBetter than 62% of packages Maintenance52 Moderate activity, may be stable Popularity2 Limited adoption so far Community9 Small or concentrated contributor base Maturity49 Maturing project, gaining track record Bus Factor1 Top contributor holds 98% of commits β€” single point of failure 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 339d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/57079587?v=4)[qwthefallen](/maintainers/qwthefallen)[@qwthefallen](https://github.com/qwthefallen) --- Top Contributors [![AshrafAmir96](https://avatars.githubusercontent.com/u/79224465?v=4)](https://github.com/AshrafAmir96 "AshrafAmir96 (49 commits)")[![semantic-release-bot](https://avatars.githubusercontent.com/u/32174276?v=4)](https://github.com/semantic-release-bot "semantic-release-bot (1 commits)") --- Tags spatieapisearchpestlaravelartisanredisoauth2mediapassportdockerpermissionsboilerplatebackendadmincommandsscout ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/owlfice-citadel/health.svg) ``` [![Health](https://phpackages.com/badges/owlfice-citadel/health.svg)](https://phpackages.com/packages/owlfice-citadel) ``` ### Alternatives [unopim/unopim UnoPim Laravel PIM 10.5k2.4k](/packages/unopim-unopim)[nasirkhan/laravel-starter A CMS like modular Laravel starter project. 1.4k2.7k](/packages/nasirkhan-laravel-starter)[typicms/base A modular multilingual CMS built with Laravel, enabling developers to manage structured content like pages, news, events, and more. 1.6k20.4k](/packages/typicms-base) PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)