Search by

simbiat / mago-rules

Simbiat

Custom linter rules for Mago

Package info

github.com/Simbiat/mago-rules

pkg:composer/simbiat/mago-rules

Statistics

Installs: 0

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

dev-main 2026-11-22 08:40 UTC

This package is auto-updated.

Last update: 2026-11-22 08:40:16 UTC


README

Warning

Replaced by Mago rules, because speed.

Custom linter rules for Mago, that are used in simbiat.eu project. It is a port of the PHP Code Sniffer sniffs (simbiat/sniffs) to the Mago extension API. Mostly generated by Claude.ai, with some clean-up and testing done afterward.

All rules are linter rules: each of them needs only the syntax tree of one file, none needs types or the analysis of several files, so there is nothing for the analyzer.

What's in here

All rules are warning by default and are enabled by default. The level and the state can be changed in mago.toml by the code of the rule.

Rule Was (PHPCS) Description Fixable?
simbiat/prefer-multibyte Simbiat.Strings.PreferMultibyte Recommend using multibyte (mb_*) functions instead of single-byte functions. Useful for projects that deal with multi-language strings and emojis. Using arguments with a name that contains one of binary, blob, bytes, raw, hash, digest, checksum, signature, ciphertext, plaintext, salt, iv, key as a whole word (for example $rawBody, $user_key, $hashes, but not $archive), will serve as a hint, that this is binary data, and thus suppress the rule. No
simbiat/multibyte-encoding Simbiat.Strings.MultibyteEncoding Highlights mb_* calls missing an explicit encoding. UTF-8 is recommended in most modern environments. Yes
simbiat/exit-code Simbiat.PHP.ExitCode Suggests adding a status code to exit/die without one for the sake of being explicit. Yes
simbiat/prefer-white-string Simbiat.PHP.PreferWhiteString Suggest using \Simbiat\StringHelpers\Sanitize::whiteString($string) call instead of preg_match('/^\s*$/', $string) === 1 to capture more whitespace characters. No
simbiat/twig-safe-filter-option Simbiat.Twig.SafeFilterOption Highlights new TwigFunction(...) / new TwigFilter(...) with is_safe flag. Using the flag bears risks, so you may want to ensure, that the function/filter is sanitized enough. No
simbiat/sql-prefer-current Simbiat.SQL.DateTimeFunctions.PreferCurrent Prefer CURRENT_* functions in SQL literals instead of UTC_* ones. UTC_* bypasses whatever timezone you are using on the server, and unless it is already UTC, can result in time-related bugs. This rule helps with that, even if you do not use UTC as default timezone (which you should). Yes
simbiat/sql-missing-precision Simbiat.SQL.DateTimeFunctions.MissingPrecision Enforce explicit precision argument for date and time functions in SQL literals. 0 by default, see --sql-precision below. Yes
simbiat/missing-unicode-flag Simbiat.Regex.MissingUnicodeFlag Highlights preg_*() literal patterns missing the u flag. Useful in projects dealing with unicode. Yes
simbiat/missing-caseless-restrict-flag Simbiat.Regex.MissingCaselessRestrictFlag Highlights preg_*() literal patterns that have both u (PCRE_UTF8) and i (PCRE_CASELESS) but not r (PCRE2_EXTRA_CASELESS_RESTRICT) to prevent matching of K (Kelvin character), when you are searching for k and K. Results in stricter matches. Yes

Installation

composer require --dev simbiat/mago-rules

Then add the extension host to mago.toml (see mago.example.toml):

[extension-hosts.simbiat]
command = ["php", "vendor/simbiat/mago-rules/bin/worker.php", "--sql-precision=0"]

Mago starts that command, and the rules run inside of that PHP process. It must be a PHP (8.4+) that can load the project's vendor folder: if your tools run in a Docker container, the command has to start the worker there (for example with docker compose exec -T).

mago extension list shows the rules that Mago loaded, and mago extension validate starts the worker and checks the registration.

Settings

Mago has no per-rule options for extensions, so the settings of a rule are options of the worker command:

Option Default Was Meaning
--sql-precision 0 precision property of Simbiat.SQL.DateTimeFunctions Fractional-second precision for simbiat/sql-missing-precision. Values outside of 0-6 are moved to the nearest one.

The level of a rule, whether it is enabled and the paths it skips are the normal [linter.rules] settings:

[linter.rules]
"simbiat/prefer-multibyte" = { enabled = false }
"simbiat/exit-code" = { level = "error" }

Ignoring a result

Use the normal Mago pragmas, with the new codes: // @mago-ignore lint:simbiat/missing-unicode-flag (replaces // phpcs:ignore Simbiat.Regex.MissingUnicodeFlag) and @mago-expect.

Fixing

mago lint --fix applies the fixes of one pass. mago fix repeats until nothing changes. Use it, when a fix of one rule makes a fix of another possible (u flag, then r flag).

Differences from the PHPCS version

  • One code per rule. Simbiat.SQL.DateTimeFunctions had two codes, and a Mago rule has one, so it became two rules. The two share the code that finds the SQL. Where UTC_TIMESTAMP needs both fixes, simbiat/sql-prefer-current makes one edit (CURRENT_TIMESTAMP(0)) and simbiat/sql-missing-precision leaves that place to it. If you turn simbiat/sql-prefer-current off, the precision of a UTC_* function is only reported, not fixed.
  • Names. The classes are *Rule instead of *Sniff and they implement Mago\Sdk\Linter\Rule. The namespaces and folders are the same. ruleset.xml is replaced by MagoExtension.php, which lists the rules.
  • Mago sees syntax, not tokens. This removed the code that worked around tokens, and changed a few edge cases, mostly in the direction of fewer mistakes:
    • exit/die have separate nodes; both are handled as before.
    • A string literal is one piece, also when it has several lines. The PHPCS fragment logic is gone, so simbiat/sql-missing-precision now fixes a call that is split over lines (NOW(\n) becomes NOW(0)), where the sniff only reported it.
    • Interpolated strings ("SELECT NOW() ... {$x}") are checked as a whole, with the interpolated code ignored. A nowdoc is still not checked.
    • The subject of simbiat/prefer-white-string is the whole argument, even if it has a comma inside a nested call.
    • A pattern for the regex rules has to be one string literal. '/a/'.$b and a named first argument are not understood (the token based version only looked at the first token, so it treated '/a/'.$b as a literal).
    • Comments between new and the class name do not hide the class from simbiat/twig-safe-filter-option.
  • Fix of the keywords of SQL. The list of the SQL keywords, that a literal has to start with, was written as ^SELECT|INSERT|…|CALL\b, where ^ and \b applied to one keyword only, so a string with UPDATE anywhere could be taken as SQL. It is a group now.
  • Settings are worker options (see above), not rule properties.

Testing

composer install
vendor/bin/phpunit

The tests run the real mago binary (vendor/bin/mago, or the path from the MAGO_BIN environment variable) with this package as the extension. The rules run in a worker process that Mago starts, and a rule cannot be called from a test directly. This also means that PHPUnit cannot see which lines of the rules were executed, so code coverage reports show only the helper code that the tests call in-process (SqlDateTimeHelper, RegexLiteralHelper).

Each fixture folder has a test class in tests/<Category>/<Name>Test.php and fixtures in tests/Fixtures/<Category>/<Name>/*.inc. The test class names the codes of its rules. tests/RuleTestCase.php does the rest: it runs only those rules on every fixture (mago lint --only) and compares the results to the directives written in the fixture (all in // comments):

Directive Meaning
// @expect code-a code-b This line must give these results (codes of rules). A line without @expect must give no result.
// @expect-next code-a The next line must give these results. Use it for multi-line strings and heredocs.
// @expect+2 code-a The same, N lines below.
// @property precision=N Set --sql-precision of the worker for the whole fixture.
// @max-passes N The fixer may need N runs of mago lint --fix for this fixture (default: 1).
// @known-issue Text The fixture describes desired behavior that the rule does not have yet. Tests are "incomplete", not failed.

If Fixture.inc.fixed exists, the fixer output must be equal to it. If it does not exist, the fixer must not change the fixture. Fixer output must always be valid PHP, and must not have fixable results left.

To add a rule: create the rule, register it in MagoExtension.php, add it to the table above, then add a test class and at least one fixture. tests/ExtensionTest.php fails until all of these exist, and until Mago itself lists the rule.