{"id":28951526,"url":"https://github.com/wardvisual/warvilphp","last_synced_at":"2025-06-23T15:05:30.648Z","repository":{"id":296388958,"uuid":"729015294","full_name":"wardvisual/warvilphp","owner":"wardvisual","description":"A lightweight Raw PHP Framework","archived":false,"fork":false,"pushed_at":"2025-05-30T15:39:23.000Z","size":1667,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-30T15:53:58.323Z","etag":null,"topics":["php","php-framework","php8","raw-php","warvilphp"],"latest_commit_sha":null,"homepage":"https://packagist.org/packages/wardvisual/warvilphp","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wardvisual.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["wardvisual"]}},"created_at":"2023-12-08T07:59:11.000Z","updated_at":"2025-05-30T15:39:26.000Z","dependencies_parsed_at":"2025-05-30T16:03:19.291Z","dependency_job_id":"2e2b87f4-ac57-4ffb-be8f-f2d90c739b16","html_url":"https://github.com/wardvisual/warvilphp","commit_stats":null,"previous_names":["wardvisual/warvilphp"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/wardvisual/warvilphp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wardvisual%2Fwarvilphp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wardvisual%2Fwarvilphp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wardvisual%2Fwarvilphp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wardvisual%2Fwarvilphp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wardvisual","download_url":"https://codeload.github.com/wardvisual/warvilphp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wardvisual%2Fwarvilphp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261500583,"owners_count":23168070,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["php","php-framework","php8","raw-php","warvilphp"],"created_at":"2025-06-23T15:05:29.935Z","updated_at":"2025-06-23T15:05:30.638Z","avatar_url":"https://github.com/wardvisual.png","language":"PHP","readme":"# WarvilPHP Framework\n\nA **lightweight PHP framework** inspired by Laravel, designed for developers who appreciate simplicity and direct access to the PHP language.\n\n![WarvilPHP](https://raw.githubusercontent.com/wardvisual/warvilphp/refs/heads/main/public/assets/warvilphp.jpg)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/PHP-v8.0+-blue.svg\" alt=\"PHP Version\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-green.svg\" alt=\"License\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Status-Alpha-red.svg\" alt=\"Status\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/API-Unstable-orange.svg\" alt=\"API Stability\"\u003e\n\u003c/p\u003e\n\n## 📋 Table of Contents\n\n- [Introduction](#-introduction)\n- [Project Status](#-project-status)\n- [Roadmap to Production Readiness](#-roadmap-to-production-readiness)\n- [Features](#-features)\n- [Requirements](#-requirements)\n- [Installation](#-installation)\n- [Directory Structure](#-directory-structure)\n- [Configuration](#-configuration)\n- [Environment Variables](#-environment-variables)\n- [Command Line Interface](#-command-line-interface)\n- [Routing System](#-routing-system)\n- [Controllers](#-controllers)\n- [Views](#-views)\n- [Models](#-models)\n- [Components](#-components)\n- [Middleware](#-middleware)\n- [Database Migrations](#-database-migrations)\n- [API Development](#-api-development)\n- [File Storage](#-file-storage)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n## 🌟 Introduction\nWarvilPHP is a lightweight MVC framework for PHP applications. It provides a clean and elegant syntax similar to Laravel but with a smaller footprint and more direct access to PHP. The framework helps you build web applications quickly without the complexity of larger frameworks.\n\n### The Story Behind WarvilPHP\n\nWarvilPHP was born out of necessity and a passion for efficient development. While working on numerous PHP projects, I found myself repeatedly recreating the same foundational structure - routing systems, database abstractions, and templating logic. This repetition felt inefficient, yet I wasn't satisfied with the complexity and overhead of existing frameworks.\n\nI wanted something that maintained the directness and flexibility of pure PHP while providing the structure and convenience of a framework. Something that would embrace PHP's strengths rather than hide them behind layers of abstraction.\n\nAfter refining this structure across multiple projects, I realized that this middle-ground approach could benefit other developers who shared my appreciation for PHP's simplicity. WarvilPHP represents that balance - a framework that provides helpful structure and tools without getting in your way or forcing you into restrictive patterns.\n\nThis framework is now open source, I'm open-sourcing WarvilPHP to help developers who want to build PHP applications with a clean architecture but without sacrificing the power and directness that made us fall in love with PHP in the first place.\n\n\n## 🚦 Project Status\n\n\u003e **⚠️ Development Status: Pre-release**\n\u003e \n\u003e WarvilPHP is currently in **pre-release development stage**. While the framework includes many functional features, it is not yet recommended for production environments or critical applications.\n\u003e \n\u003e Following semantic versioning standards:\n\u003e - Current releases (v0.x.x) are considered development/alpha versions\n\u003e - Future v1.0.0 will mark the first stable, production-ready release\n\u003e\n\u003e We encourage developers to explore WarvilPHP for personal projects, learning purposes, or non-critical applications. Your feedback during this phase is invaluable to the project's growth!\n\n## 🗺️ Roadmap to Production Readiness\n\nWe're following semantic versioning (semver.org) with a clear path to a stable v1.0.0 release:\n\n- [x] **v0.1.0-alpha** (Current)\n  - Initial framework architecture\n  - Basic MVC implementation\n  - Routing system for web and API\n  - Command line interface\n  - Development server via `php warvil serve`\n  - View templating and components\n\n- [ ] **v0.2.0-alpha**\n  - Enhanced database ORM functionality\n  - Improved middleware system\n  - Extended validation capabilities\n  - File storage improvements\n  - Authentication scaffolding\n\n- [ ] **v0.5.0-beta**\n  - Complete test coverage for core components\n  - Performance optimization\n  - Security hardening\n  - Comprehensive error handling\n  - Extended documentation with examples\n\n- [ ] **v0.9.0-rc** (Release Candidate)\n  - Feature-complete implementation\n  - Production deployment guides\n  - API stabilization\n  - Backward compatibility guarantees\n\n- [ ] **v1.0.0** (Stable Release)\n  - Production-ready code\n  - Complete documentation\n  - Long-term support plan\n  - Community-tested in various environments\n\nAfter v1.0.0, we will strictly follow semantic versioning:\n- MAJOR version for incompatible API changes (v2.0.0)\n- MINOR version for backwards-compatible functionality (v1.1.0)\n- PATCH version for backwards-compatible bug fixes (v1.0.1)\n\nWe welcome contributors to help us reach these milestones faster! See our [Contributing](#-contributing) section for details on how to get involved.\n\n## ✨ Features\n\n- **🏗️ MVC Architecture**: Clean separation of Model, View and Controller\n- **🌐 Routing System**: Simple and intuitive routing for both web and API endpoints\n- **🗄️ Database ORM**: Lightweight database abstraction and query building\n- **🔧 CLI Commands**: Built-in command line tools for scaffolding\n- **🧩 Component-based Views**: Reusable view components\n- **🛡️ Middleware Support**: Request filtering capabilities\n- **🔁 API Response Handling**: Tools for building RESTful APIs\n- **🔐 Environment Variables**: Secure configuration management\n- **📁 File Storage**: Simple file storage management\n\n## 🛠️ Requirements\n\n- PHP 8.0 or higher\n- Composer\n- MySQL Database\n- PDO PHP Extension\n- JSON PHP Extension\n- FileInfo PHP Extension\n\n## 🚀 Installation\n\n### Option 1: Via Composer Create-Project\n\n```bash\ncomposer create-project wardvisual/warvilphp your-project-name\ncd your-project-name\ncomposer serve\n```\n\n## 📂 Directory Structure\n\n```text\nwarvilphp/\n├── app/                  # Application code\n│   ├── controllers/      # Controllers\n│   ├── core/             # Framework core files\n│   │   ├── utils/        # Framework utilities\n│   ├── database/         # Database files\n│   │   ├── sql/          # SQL migrations\n│   │   ├── factories/    # Model factories\n│   ├── middlewares/      # Middlewares\n│   ├── models/           # Models\n│   ├── routes/           # Route definitions\n│   ├── services/         # Service classes\n│   ├── shared/           # Shared components\n│   │   ├── components/   # View components\n│   │   ├── layouts/      # View layouts\n│   │   ├── errors/       # Error pages\n│   ├── traits/           # PHP traits\n│   ├── views/            # Views\n│   ├── [bootstrap.php]   # Application bootstrap\n│   └── [init.php]        # Manual initialization\n├── bin/                  # Binary/executable files\n│   ├── install           # Installation script\n│   ├── warvil            # CLI command runner\n│   └── [warvil.bat]      # Windows CLI command runner\n├── cli/                  # CLI command definitions\n├── public/               # Publicly accessible files\n│   ├── assets/           # Assets (images, fonts)\n│   ├── js/               # JavaScript files\n│   ├── styles/           # CSS files\n│   └── uploads/          # Uploaded files\n├── vendor/               # Composer packages\n├── .env                  # Environment variables\n├── [.env.example]        # Environment example\n├── .gitignore            # Git ignored files\n├── .htaccess             # Apache configuration\n├── [composer.json]       # Composer configuration\n├── [index.php]           # Application entry point\n└── [warvil.json]         # Framework configuration\n```\n\n## ⚙️ Configuration\nWarvilPHP uses a JSON configuration file (warvil.json) for application settings\n```json\n  \"name\": \"warvilphp\",\n  \"version\": \"1.0.0\",\n  \"description\": \"WarvilPHP, A lightweight PHP framework\",\n  \"author\": \"Wardvisual \u003cwardvisual@gmail.com\u003e\",\n  \"keywords\": [\"php\", \"framework\", \"warvilPHP\"],\n  \"database\": {\n    \"driver\": \"mysql\",\n    \"host\": \"localhost\",\n    \"dbname\": \"your_database\",\n    \"username\": \"root\",\n    \"password\": \"\"\n  },\n  \"paths\": {\n    \"public\": \"public\",\n    \"controllers\": \"app/controllers\",\n    \"models\": \"app/models\",\n    \"views\": \"app/views\"\n  }\n}\n```\n## 🔐 Environment Variables\nSensitive configuration like database credentials should be stored in the .env file:\n\n```.env\nAPP_NAME=WarvilPHP\nAPP_ENV=local\nAPP_DEBUG=true\nAPP_URL=http://localhost\nAPP_KEY=base64:your-random-key-here\n\nDB_DRIVER=mysql\nDB_HOST=localhost\nDB_PORT=3306\nDB_DATABASE=warvilphp\nDB_USERNAME=root\nDB_PASSWORD=\n\nSTORAGE_DIRECTORY=/public/uploads\nSTORAGE_MAX_SIZE=1000000\n```\n\nGenerate a secure application key:\n```sh\nphp warvil key:generate\n```\n\n## 🖥️ Command Line Interface\nWarvilPHP comes with a command-line tool called warvil for scaffolding components:\n\n#### Development\n```sh\n# Start development server\nphp warvil serve\n# OR with custom host and port\nphp warvil serve localhost 3000\n\n# Show help\nphp warvil help\n```\n#### Generator Commands\n```sh\n# Create a controller\nphp warvil make:controller UserController\n\n# Create a model\nphp warvil make:model User\n\n# Create a view\nphp warvil make:view users/index\n\n# Create a middleware\nphp warvil make:middleware Auth\n\n# Create a component\nphp warvil make:component buttons/primary\n\n# Create a service\nphp warvil make:service UserService\n\n# Create an API controller\nphp warvil make:api ProductController\n\n# Create a layout\nphp warvil make:layout admin\n\n# Create a database table schema\nphp warvil make:table Users\n\n```\n#### Database Commands\n```sh\nphp warvil migration:run User:up\n```\n\n#### Utility Commands\n```sh\n# Generate an application key\nphp warvil key:generate\n```\n\n## 🌐 Routing System\nWarvilPHP has two types of routes: web routes and API routes.\n\nWeb Routes (app/routes/web.php)\n```php\nuse app\\core\\Router;\n\n// Simple route with controller and method\nRouter::get('/', 'Home', 'index');\n\n// Route with callback function\nRouter::get('/about', null, function() {\n    echo 'About page';\n});\n\n// Route with POST method\nRouter::post('/contact', 'Contact', 'submit');\n```\n\nAPI Routes (app/routes/api.php)\n\n```php\nuse app\\core\\RouterApi;\n\n// API routes are automatically prefixed with /api\nRouterApi::get('/', 'HomeController', 'index');\nRouterApi::post('/users', 'UserController', 'store');\n```\n\n\n## 🎮 Controllers\nControllers handle request logic and return responses:\n```php\nnamespace app\\controllers;\n\nuse app\\core\\Controller;\nuse app\\core\\Request;\nuse app\\core\\Response;\nuse app\\models\\User;\n\nclass UserController extends Controller\n{\n    public function index(): void\n    {\n        $users = (new User())-\u003eall();\n        $this-\u003eview('users/index', ['users' =\u003e $users]);\n    }\n\n    public function store(): void\n    {\n        $data = Request::validate([\n            'name' =\u003e 'required|min:3',\n            'email' =\u003e 'required|email',\n        ]);\n        \n        $user = new User();\n        $user-\u003ecreate($data);\n        \n        Response::json([\n            'success' =\u003e true,\n            'message' =\u003e 'User created successfully'\n        ]);\n    }\n}\n```\n\n\n## 👁️ Views\nViews are PHP files that contain HTML with embedded PHP code:\n```php\n\u003c!-- app/views/users/index.php --\u003e\n\u003cdiv class=\"container\"\u003e\n    \u003ch1\u003eUsers\u003c/h1\u003e\n    \n    \u003cdiv class=\"user-list\"\u003e\n        \u003c?php foreach($users as $user): ?\u003e\n            \u003cdiv class=\"user-card\"\u003e\n                \u003ch3\u003e\u003c?= $user['name'] ?\u003e\u003c/h3\u003e\n                \u003cp\u003e\u003c?= $user['email'] ?\u003e\u003c/p\u003e\n            \u003c/div\u003e\n        \u003c?php endforeach; ?\u003e\n    \u003c/div\u003e\n\u003c/div\u003e\n```\n\nLayouts\nLayouts provide a template for your views:\n\n```php\n\u003c!-- app/shared/layouts/main.php --\u003e\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n    \u003ctitle\u003e\u003c?= htmlspecialchars($warvilConfig['name']) ?\u003e\u003c/title\u003e\n    \u003cmeta charset=\"UTF-8\"\u003e\n    \u003clink rel=\"stylesheet\" href=\"\u003c?= htmlspecialchars($baseStyle) ?\u003e\"\u003e\n    \u003c?php echo $cssPath ? '\u003clink rel=\"stylesheet\" href=\"' . htmlspecialchars($cssPath) . '\"\u003e' : ''; ?\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003cheader\u003e\n        \u003c!-- Header content --\u003e\n    \u003c/header\u003e\n    \n    \u003cmain\u003e\n        \u003c?= $this-\u003econtent ?\u003e\n    \u003c/main\u003e\n    \n    \u003cfooter\u003e\n        \u003c!-- Footer content --\u003e\n    \u003c/footer\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n\n\n## 🗄️ Models\nModels represent database tables and handle data operations:\n```php\nnamespace app\\models;\n\nuse app\\core\\Model;\n\nclass User extends Model\n{\n    public function __construct()\n    {\n        parent::__construct('users');\n    }\n    \n    public function findByEmail($email)\n    {\n        return $this-\u003egetByField('email', $email);\n    }\n}\n```\n\nUsing models:\n```php\n$user = new User();\n\n// Create\n$user-\u003ecreate([\n    'username' =\u003e 'john_doe',\n    'email' =\u003e 'john@example.com'\n]);\n\n// Read all records\n$allUsers = $user-\u003eall();\n\n// Find by ID\n$singleUser = $user-\u003egetById(1);\n\n// Update\n$user-\u003eupdate(1, [\n    'username' =\u003e 'jane_doe'\n]);\n\n// Delete\n$user-\u003edelete(1);\n```\n\n\n\n## 🧩 Components\nComponents are reusable view partials:\n\n```php\n// app/shared/components/card/index.php\nfunction Card($data, $onclick)\n{\n    ?\u003e\n    \u003cdiv class=\"card\"\u003e\n        \u003ch3\u003e\u003c?= $data['title'] ?\u003e\u003c/h3\u003e\n        \u003cp\u003e\u003c?= $data['content'] ?\u003e\u003c/p\u003e\n        \u003cbutton onclick=\"\u003c?= $onclick ?\u003e(\u003c?= $data['id'] ?\u003e)\"\u003e\n            \u003c?= $data['buttonText'] ?\u003e\n        \u003c/button\u003e\n    \u003c/div\u003e\n    \u003c?php\n}\n```\n\n\nUsing components in views:\n```php\n\u003c!-- In a view file --\u003e\n\u003c?php Card([\n    'id' =\u003e 1,\n    'title' =\u003e 'Example Card',\n    'content' =\u003e 'This is the content of the card',\n    'buttonText' =\u003e 'Click me'\n], 'handleClick'); ?\u003e\n```\n\n\n## 🛡️ Middleware\nMiddleware filters HTTP requests:\n\n```php\nnamespace app\\middlewares;\n\nuse app\\core\\Request;\nuse app\\core\\Response;\n\nclass Auth\n{\n    public function handle(Request $request, $next)\n    {\n        // Check if user is authenticated\n        if (!isset($_SESSION['user_id'])) {\n            return Response::json(['error' =\u003e 'Unauthorized'], 401);\n        }\n        \n        // Continue to next middleware or controller\n        return $next($request);\n    }\n}\n```\n\n\n## 🔄 Database Migrations\nCreate and manage database tables:\n\n```php\n// app/database/sql/User.php\nuse app\\core\\Model;\n\nrequire_once 'app/init.php';\n\nclass User extends Model\n{\n    /**\n     * Run the migrations.\n     */\n    public function up()\n    {\n        $this-\u003edown();\n        $fields = [\n            'id' =\u003e 'INT PRIMARY KEY AUTO_INCREMENT',\n            'username' =\u003e 'VARCHAR(255)',\n            'email' =\u003e 'VARCHAR(255)',\n            'password' =\u003e 'VARCHAR(255)',\n            'created_at' =\u003e 'TIMESTAMP DEFAULT CURRENT_TIMESTAMP',\n            'updated_at' =\u003e 'TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP'\n        ];\n\n        $this-\u003ecreateTable('users', $fields);\n    }\n\n    /**\n     * Reverse the migrations.\n     */\n    public function down()\n    {\n        $this-\u003edropTable('users');\n    }\n}\n```\n\nUsing components in views:\n```sh\nphp warvil migration:run User:up\n```\n\n## 🔌 API Development\nWarvilPHP provides tools for easy API development:\n\n```php\nnamespace app\\controllers;\n\nuse app\\core\\Controller;\nuse app\\core\\Request;\nuse app\\core\\Response;\nuse app\\models\\User;\n\nclass UserController extends Controller\n{\n    public function index(): void\n    {\n        $users = (new User())-\u003eall();\n        Response::json(['data' =\u003e $users]);\n    }\n    \n    public function store(): void\n    {\n        try {\n            $data = Request::validate([\n                'username' =\u003e 'required|min:3',\n                'email' =\u003e 'required|email',\n            ]);\n            \n            $user = new User();\n            $user-\u003ecreate($data);\n            \n            Response::json([\n                'success' =\u003e true,\n                'message' =\u003e 'User created successfully'\n            ], 201);\n        } catch (\\Exception $e) {\n            Response::status(400)-\u003ejson([\n                'success' =\u003e false,\n                'message' =\u003e $e-\u003egetMessage()\n            ]);\n        }\n    }\n}\n\n```\n\n\n\n\n## 📁 File Storage\nHandle file uploads:\n```php\nuse app\\core\\Storage;\n\n// In a controller method\npublic function uploadProfilePicture(): void\n{\n    $file = $_FILES['profile_picture'];\n    $uploadPath = Storage::upload($file);\n    \n    if ($uploadPath) {\n        Response::json([\n            'success' =\u003e true,\n            'path' =\u003e $uploadPath\n        ]);\n    } else {\n        Response::status(400)-\u003ejson([\n            'success' =\u003e false,\n            'message' =\u003e 'Upload failed'\n        ]);\n    }\n}\n\n```\n\nConfigure storage in `.env` and `warvil.json`:\n```env\nSTORAGE_DIRECTORY=/public/uploads\nSTORAGE_MAX_SIZE=1000000\n```\n```json\n\"storage\": {\n  \"directory\": \"/public/uploads\",\n  \"max_size\": 1000000,\n  \"allowed_types\": [\"jpg\", \"jpeg\", \"png\", \"gif\"]\n}\n```\n\n\n## 🤝 Contributing\nContributions are welcome! Please feel free to submit a Pull Request\n\n1. Fork the Project\n2. Create your Feature Branch (git checkout -b feature/amazing-feature)\n3. Commit your Changes (git commit -m 'Add some amazing feature')\n4. Push to the Branch (git push origin feature/amazing-feature)\n5. Open a Pull Request\n\n## 📄 License\nWarvilPHP is open-sourced software licensed under the MIT license.\n\n\n\u003cp align=\"center\"\u003e\n  \u003csmall\u003eWarvilPHP is under active development. While we strive for stability, use in production is at your own risk.\u003c/small\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e Made with ❤️ by \u003ca href=\"https://github.com/wardvisual\"\u003eWardVisual\u003c/a\u003e \u003c/p\u003e","funding_links":["https://github.com/sponsors/wardvisual"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwardvisual%2Fwarvilphp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwardvisual%2Fwarvilphp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwardvisual%2Fwarvilphp/lists"}