Coding Standards Laravel Package

Getting Started

Install as a dev dependency (Laravel projects almost never need this in production):

composer require --dev joomla/coding-standards squizlabs/php_codesniffer
composer require --dev --no-update dealerdirect/phpcodesniffer-composer-installer
composer update --lock

Or, if you already have PHPCS installed, just add the standard:

vendor/bin/phpcs -i          # confirm "Joomla" appears in the installed standards list

Where to look first:

1. README.md top warning — since Joomla 4.2, PHP code uses PSR-12, so the Joomla PHP sniffs are effectively legacy. Only the JS/CSS/HTML/XML sniffs are still authoritative.
2. Joomla/ruleset.xml — read this before adopting the standard wholesale; it composes other standards and is what you'd copy if you need to trim sniffs.
3. manual/ — the human-facing coding standards docs; more current than the sniffs themselves.

First realistic use case: you're maintaining a Joomla extension (or a shared component library) alongside a Laravel app, and you want a lint baseline before porting business logic into Laravel. Run:

vendor/bin/phpcs --standard=Joomla path/to/extensions/com_foo -p --report=summary

If you're not shipping or touching Joomla code, do not install this — use laravel/pint (PSR-12 + Laravel style) instead. This package is a niche bridge, not a general PHP standard.

Implementation Patterns

1. Layered ruleset (recommended). Keep Joomla sniffs scoped to Joomla-shaped directories, PSR-12 for the rest of your Laravel app. Create phpcs.xml.dist at repo root:

<?xml version="1.0"?>
<ruleset name="Mixed">
  <file>app</file>
  <file>database</file>
  <!-- Legacy Joomla code, will be ported -->
  <file>legacy/joomla-ext</file>

  <rule ref="PSR12">
    <exclude-pattern>legacy/joomla-ext/*</exclude-pattern>
  </rule>

  <rule ref="Joomla">
    <include-pattern>legacy/joomla-ext/*</include-pattern>
    <!-- Only keep sniffs that still have value: JS/CSS/XML -->
    <exclude name="Joomla.ControlStructures"/>
    <exclude name="Joomla.Classes"/>
  </rule>
</ruleset>

2. Selective sniffing. Since PHP sniffs are stale post-4.2, include only the sniff categories you actually need:

<rule ref="Joomla.Files.SideEffects"/>
<rule ref="Joomla.Commenting.FunctionComment"/>

3. Composer script for day-to-day use. Mirror how you run Pint:

"scripts": {
  "lint:joomla": "phpcs --standard=phpcs.xml.dist legacy/",
  "fix:joomla": "phpcbf --standard=phpcs.xml.dist legacy/"
}

Then composer lint:joomla in CI and before PRs that touch the legacy/ directory.

4. CI integration. Split jobs by directory so a Joomla-sniff failure doesn't block Laravel code:

- run: vendor/bin/phpcs --standard=PSR12 app database
- run: vendor/bin/phpcs --standard=Joomla legacy/joomla-ext --report=checkstyle --report-file=phpcs-joomla.xml

5. Porting workflow. Use the Joomla standard as a baseline metric: run it before and after converting an extension class into a Laravel service. Sniff counts going from ~40 to ~5 is a rough proxy for how much Joomla-ism you've stripped out. Then run PSR-12/Pint to bring the result into Laravel shape.

6. Editor integration. Point PhpStorm's Code Sniffer inspection at the Joomla standard only for legacy/** paths; use Pint/PHP-CS-Fixer for app/**. Don't let both run on the same file — they'll fight.

Gotchas and Tips

• The PHP standard is deprecated in spirit. Joomla 4.2+ follows PSR-12. If you're starting fresh, don't adopt Joomla for PHP — adopt PSR12 or laravel/pint. Use this only for JS/CSS/XML sniffing or to audit pre-4.2 extensions.
• GPL-2.0 license is a real concern. Copying sniff code from this package into your own project can drag GPL obligations into your Laravel app. Running it as a dev-only tool in require-dev is generally fine, but don't fork/embed sniffs into shipped code without legal review. Most Laravel shops want MIT-clean dependencies.
• Last release: Sept 2020. PHPCS has moved from v3 to v4 and Squizlabs is now under PHPCSStandards. Expect to pin squizlabs/php_codesniffer: ^3.5 to keep the ruleset working; older sniffs may emit deprecation notices or fail under PHPCS 4.
• dealerdirect/phpcodesniffer-composer-installer is deprecated. Use phpcsstandards/composer-installer instead, otherwise you may see install warnings or standards not registering. Confirm with phpcs -i.
• Auto-fix is partial. phpcbf handles whitespace, ordering, and some formatting, but not comment/annotation sniffs. Always git diff before committing phpcbf output on legacy directories.
• Debugging which sniff fires: phpcs --standard=Joomla --report=source legacy/ gives a per-sniff count; -s on a normal report prints sniff code (e.g., Joomla.ControlStructures.ControlSignature.NewlineAfterOpenBrace) so you can search the ruleset and target // phpcs:ignore precisely.
• Inline suppression: // phpcs:ignore Joomla.Commenting.FunctionComment.MissingParamTag — always include the sniff name, otherwise you silently disable future rules on the line.
• Conflicts with Pint/PHP-CS-Fixer. Different engines, different configs. If both are wired to the same path, you'll get a fix-loop. Keep paths disjoint.
• Extension point: if you need Joomla-ish rules with local tweaks, fork the Joomla/ruleset.xml into phpcs-joomla-local.xml in your repo and ref individual sniffs, rather than depending on files inside vendor/. That protects you when the (rare) release lands.
• Config quirk: the Joomla ruleset enforces tab indentation in several sniffs. Mixed tabs/spaces in a Laravel repo will produce noisy diffs. Disable tab-related sniffs (--exclude=Joomla.WhiteSpace.* if available) if you're only auditing logic shape.
• Nothing depends on this package (0 dependents) and its last release is 4+ years old — treat it as frozen infrastructure. Budget for pinning versions and owning local copies of any sniff you rely on.