PHPackages hisoft/laravel-conventions - 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. [Utility & Helpers](/categories/utility) 4. / 5. hisoft/laravel-conventions ActiveLibrary[Utility & Helpers](/categories/utility) hisoft/laravel-conventions ========================== Engineering conventions for Laravel projects v1.3.0(2mo ago)21681MITPHPPHP ^8.2 Since Feb 5Pushed 2mo agoCompare [ Source](https://github.com/hisoft-br/laravel-conventions)[ Packagist](https://packagist.org/packages/hisoft/laravel-conventions)[ RSS](/packages/hisoft-laravel-conventions/feed)WikiDiscussions main Synced 2d ago READMEChangelogDependencies (8)Versions (7)Used By (0) Laravel Conventions =================== [](#laravel-conventions) Engineering conventions for Laravel projects, designed to enforce a professional architecture, faster refactors, and AI-assisted development that stays on-rails. What This Enables ----------------- [](#what-this-enables) - Consistent structure across teams and projects - Refactors that are predictable, safe, and fast - Clean separation of concerns (Actions, Requests, Resources) - Strong testing posture with clear boundaries - AI outputs aligned with your standards, not random guesses Refactor Impact (Example) ------------------------- [](#refactor-impact-example) Before: mixed responsibilities in controllers, implicit rules, inconsistent naming. After: Actions own business logic, Requests handle validation, Resources define API shape, and naming stays in English across the stack. Installation ------------ [](#installation) ``` composer require hisoft/laravel-conventions --dev ``` Usage ----- [](#usage) This package supports two types of Laravel projects: ### API Projects [](#api-projects) For backend/REST API projects: ``` php artisan vendor:publish --tag=hisoft-api ``` Publishes: - Shared conventions (architecture, exceptions, testing, PHPDocs, static analysis) - API-specific conventions (CRUD, Resources) ### Inertia Projects [](#inertia-projects) For modern monolith projects with Vue/React: ``` php artisan vendor:publish --tag=hisoft-inertia ``` Publishes: - Shared conventions (architecture, exceptions, testing, PHPDocs, static analysis) - Inertia-specific conventions (Pages, Forms, Props, Components) Published Structure ------------------- [](#published-structure) ``` AGENTS.md # Global agent rules (published to project root) .ai/ upstream/ # Package conventions (do not edit) conventions.md exceptions.md testing.md phpdocs.md static-analysis.md # API: crud.md, resources.md # Inertia: pages.md, forms.md, props.md, components.md local/ # Project-specific overrides (editable) overrides.md ``` AI Tools Integration -------------------- [](#ai-tools-integration) ### Cursor IDE [](#cursor-ide) Install Cursor rules so the editor loads Hisoft conventions when editing matching files. **API project (conventions only):** ``` php artisan hisoft:cursor --api ``` **Inertia project (conventions only):** ``` php artisan hisoft:cursor --inertia ``` **Conventions + RPI workflow (recommended for complex work in Cursor):** ``` php artisan hisoft:cursor --api --rpi # or php artisan hisoft:cursor --inertia --rpi ``` **RPI only** (e.g. you already manage conventions elsewhere): ``` php artisan hisoft:cursor --rpi ``` This creates: - `.cursor/rules/hisoft.mdc` — points the AI to `.ai/upstream/*` and `.ai/local/overrides.md` (when `--api` or `--inertia` is used) - `.cursor/rules/rpi.mdc` — lightweight **always-on** overview of the RPI process (when `--rpi` is used) - `.cursor/skills//SKILL.md` — native Cursor **skills** for each RPI phase (`brainstorm`, `research`, `plan`, `iterate`, `implement`, `investigate`), with templates under `brainstorm/`, `research/`, and `plan/` subfolders **How to use RPI in Cursor** 1. After install, `rpi.mdc` is always applied so the model knows the workflow exists. 2. In Chat, run a **slash command** like **`/brainstorm`**, **`/research`**, **`/plan`**, **`/iterate`**, **`/implement`**, or **`/investigate`** (same idea as Claude Code). You can also attach a skill as context with **`@brainstorm`**, etc. 3. Describe your goal or paste paths to artifacts under `docs/rpi/`. 4. Artifacts are written under `docs/rpi/{brainstorm,research,plan,investigate}/`. Full detail: [resources/cursor/README.md](resources/cursor/README.md). **Globs** - **API**: rules apply when editing PHP (`**/*.php`) - **Inertia**: PHP and frontend (`**/*.{php,vue,ts,tsx,js,jsx}`) **`hisoft:cursor` options** OptionPurpose`--api`Install API `hisoft.mdc``--inertia`Install Inertia `hisoft.mdc``--rpi`Install RPI overview rule + `.cursor/skills/` (native skills)`--force`Overwrite without confirmationWith **no options**, the command interactively asks for project type and whether to install RPI. In **non-interactive** mode you must pass at least one of `--api`, `--inertia`, or `--rpi`. The same RPI methodology is also authored for **Claude Code** under `resources/claude/` (agents + skills); Cursor uses **native skills** plus `rpi.mdc` under `resources/cursor/` (see [resources/cursor/README.md](resources/cursor/README.md)). ### GitHub Copilot [](#github-copilot) Install Copilot instructions to guide AI-assisted development: **For API projects:** ``` php artisan hisoft:copilot --api ``` **For Inertia projects:** ``` php artisan hisoft:copilot --inertia ``` This creates `.github/copilot-instructions.md` which GitHub Copilot automatically reads to understand project conventions. ### Copilot options [](#copilot-options) - `--api` — Install for API projects (PHP only) - `--inertia` — Install for Inertia projects (PHP + Vue/React) - `--force` — Overwrite existing file without confirmation If no option is provided, the command prompts for project type. ### Global Agent Rules [](#global-agent-rules) The publish tags also install `AGENTS.md` in the project root, providing global rules that work across all AI tools. ### Other Tools [](#other-tools) The conventions in `.ai/` are compatible with any AI-assisted development tool. Reference the files in your tool's context as needed. Updating to a Newer Package Version ----------------------------------- [](#updating-to-a-newer-package-version) When a new release of `hisoft/laravel-conventions` is published: 1. **Update Composer** ``` composer update hisoft/laravel-conventions ``` 2. **Republish convention files from the package** ``` php artisan vendor:publish --tag=hisoft-api --force # or php artisan vendor:publish --tag=hisoft-inertia --force ``` **`--force` overwrites** every path in that tag, including `.ai/upstream/*` **and** `.ai/local/overrides.md`. Back up `.ai/local/overrides.md` first if you customized it, then restore or merge after publishing. Without `--force`, Laravel **skips** existing files (safe for local edits, but upstream will not refresh). 3. **Refresh Cursor rules and RPI assets** (if you use Cursor) ``` php artisan hisoft:cursor --api --rpi --force # or --inertia --rpi ``` 4. **Refresh Copilot instructions** (if you use Copilot) ``` php artisan hisoft:copilot --api --force # or --inertia ``` Re-run only the steps that apply to your team’s tooling. Priority Order -------------- [](#priority-order) When conventions conflict: 1. `.ai/local/*` (project-specific rules) 2. `.ai/upstream/*` (package conventions) Conventions Overview -------------------- [](#conventions-overview) ### Shared (both API and Inertia) [](#shared-both-api-and-inertia) FileDescription`conventions.md`Architectural principles and layer responsibilities`exceptions.md`Domain exception handling patterns`testing.md`Testing strategy with Pest`phpdocs.md`PHPDoc conventions for code documentation`static-analysis.md`PHPStan/Larastan level 5 conventions### API-specific [](#api-specific) FileDescription`crud.md`CRUD implementation guidelines`resources.md`Laravel Resources and API response patterns### Inertia-specific [](#inertia-specific) FileDescription`pages.md`Page component structure and naming`forms.md`Form handling with useForm`props.md`Data sharing and HandleInertiaRequests`components.md`Reusable component conventionsDevelopment ----------- [](#development) Run tests: ``` docker compose run --rm test ``` Run static analysis: ``` composer analyse ``` License ------- [](#license) MIT ### Health Score 44 — FairBetter than 90% of packages Maintenance85 Actively maintained with recent releases Popularity19 Limited adoption so far Community12 Small or concentrated contributor base Maturity51 Maturing project, gaining track record Bus Factor2 2 contributors hold 50%+ of commits 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 Every ~20 days Total 4 Last Release 87d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/18430002?v=4)[Marco Fernandes](/maintainers/marcofer2010)[@marcofer2010](https://github.com/marcofer2010) --- Top Contributors [![marcofer2010](https://avatars.githubusercontent.com/u/18430002?v=4)](https://github.com/marcofer2010 "marcofer2010 (9 commits)")[![rpaggi](https://avatars.githubusercontent.com/u/1770406?v=4)](https://github.com/rpaggi "rpaggi (5 commits)")[![Douglas-Strey](https://avatars.githubusercontent.com/u/79382237?v=4)](https://github.com/Douglas-Strey "Douglas-Strey (2 commits)")[![Joao-Messias](https://avatars.githubusercontent.com/u/68703050?v=4)](https://github.com/Joao-Messias "Joao-Messias (2 commits)")[![rpaggi-hisoft](https://avatars.githubusercontent.com/u/184323839?v=4)](https://github.com/rpaggi-hisoft "rpaggi-hisoft (1 commits)") ### Code Quality TestsPest Static AnalysisPHPStan ### Embed Badge ![Health badge](/badges/hisoft-laravel-conventions/health.svg) ``` [![Health](https://phpackages.com/badges/hisoft-laravel-conventions/health.svg)](https://phpackages.com/packages/hisoft-laravel-conventions) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)