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.2.0(3mo ago)2351MITPHPPHP ^8.2

Since Feb 5Pushed 3mo 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 1mo ago

READMEChangelogDependencies (4)Versions (4)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 to automatically load conventions when working with project files:

**For API projects:**

```
php artisan hisoft:cursor --api
```

**For Inertia projects:**

```
php artisan hisoft:cursor --inertia
```

This creates `.cursor/rules/hisoft.mdc` which automatically loads the conventions when working with relevant files.

- **API**: Rules are loaded when editing PHP files (`**/*.php`)
- **Inertia**: Rules are loaded when editing PHP or frontend files (`**/*.{php,vue,ts,tsx,js,jsx}`)

### 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.

### Shared Options

[](#shared-options)

Both commands support the following 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 will prompt you to choose the 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.

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

41

—

FairBetter than 89% of packages

Maintenance81

Actively maintained with recent releases

Popularity14

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 60% 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

Every ~0 days

Total

3

Last Release

101d 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)")[![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)