Improves SPDX header linting to ensure consistent license metadata across
the codebase.
Key changes:
- Enforce deterministic tag ordering (License-Identifier, FileCopyrightText,
FileContributor) to ensure consistency, prevent merge conflicts, and
simplify code reviews
- Add contributor alias mapping to consolidate contributors with multiple
emails or name variations (e.g., "nickl-" → "Nick Lombard")
- Add --contributions-strategy option with "blame" (current code authors)
and "log" (all historical contributors) to support different attribution
philosophies
- Add optional path argument to lint specific files or directories
- Add --fix option to automatically correct header issues
Assisted-by: Claude Code (claude-opus-4-5-20251101)
We had different ways of saving and loading files from `data/`, so I decided to
unify them to simplify things. I repurposed the `DomainInfo` class and named it
`DataLoader`, so we can use the same class to load anything from the `data/`
directory.
When we change the contract of a validator, or create a new one, we need to
ensure that the mixin for the validator is present and matches the validator's
constructor.
This commit changes the current class that generates those mixin classes,
converting it into a linter so we can run it in the GitHub workflow to check for
missing changes.
Introduces a Markdown linter for checking the Changelog format.
"See Also" was transformed into a section to make it easier to
handle it with the `Content` class. The "Related" linter was
simplified to reflect that change too.
An additional "alignment" parameter was added to markdown table
generators, allowing the padding and headers to be explicitly
marked with a specific left (-1), middle (0) or right(1)
alignment.
Existing files were fixed using the `fix` option after the
changes.
The `reuse lint` command only checks for REUSE compliance, which
will accept all sorts of SPDX headers.
In this project, however, we have also other conventions. For
example, we require all PHP and docs files from the project
to have a specific license (not just any license) and also a
specific File Copyright Text (not just any copyright).
This commit introduces a command to solve this problem, validating
the headers more thoroughly.
The introduced command also does some dogfooding, using validators
from the library itself to perform some of its tasks, namely: Call,
Each, Contains, Templated and Named, showcasing potential different
use cases for the project.
This commit introduces REUSE compliance by annotating all files
with SPDX information and placing the reused licences in the
LICENSES folder.
We additionally removed the docheader tool which is made obsolete
by this change.
The main LICENSE and copyright text of the project is now not under
my personal name anymore, and it belongs to "The Respect Project
Contributors" instead.
This change restores author names to several files, giving the
appropriate attribution for contributions.
This commit concludes the effort to make all current validators
serializable by fixing the remaining ones.
The ability to use `finfo` instances on some filesystem validators
was removed. `Image` was refactored to be a readonly class.
A command was added to the main `composer qa` flow that checks
if all validators are covered by smoke tests (which are currently
used by benchmarks and serialization tests). Therefore, this commit
also ensures that every validator has a benchmark.
There's more value on showing how `assert()` displays the validation
messages than simply showing if `isValid()` returns `true` or `false`.
However, that increases the chances of having outdated documentation, so
I created a doc linter that updates the Markdown files with the
correct message.
We don't often change the tempaltes of validators, but when we do it's
extremely important that the documentation of the validators match the
exact template the validator has.
When we make changes to the code, renaming variables, or adding
parameters to a validator, it's easy to forget to update the
documentation.
With this change, we avoid having a disparity between the documentation
and the code.
When we make changes to the category of a validator, it's easy to forget
to update overall list of validators. This commit a GitHub actions that
will run a console command to check if the documentation it up-to-date.
The job will fail when we need to change the document, but the console
command will fix the issues, so there isn't a lot of friction there.
It makes more sense to use PHP to generate PHP code than to use Bash. I
love writing Bash scripts, but I know it's not for everyone, and they
can become quite complex. Porting them to PHP code also lowers the
barrier for people to change them.
While I was making those changes, I also noticed a problem with how we
save the domain suffixes. We're converting all of them to ASCII, so we
are not preserving languages such as Chinese, Thai, and Hebrew, which
use non-ASCII characters.
The name "rule" has always been confusing to me. It can be when you talk
about "validation rules", but it’s a very verbose way to describe it,
and it doesn’t work all the time.
This commit will rename the interface `Rule` to `Validator`, but it will
also rename the concept of "rule" to "validator".
The `Validator` class implements the Builder patterns, because it builds
a complex validator within a chain. This is a major breaking change, as
the `Validator` class is the foundation of the library. However, that’s
something relatively easy to replace everywhere.
This rule behaves similarly to ``Each, but the difference is that it
presents the messages in a simpler manner. This allows users to have a
simpler message when validating all items in an array or iterable
value.
I’m also introducing the `all` prefix, making it easier for users to
apply the `All` rule in combination with other rules.
Since we have the ability to use `not` as a prefix, having rules that
validate negative behaviour makes them a bit inflexible, verbose, and
harder to understand.
This commit will refactor the `NotEmpty`, and rename it to `Falsy`. It
will no longer trim strings, because Blank does a much better job at it;
it only simulates the behaviour of PHP’s native `empty()` function.
Because `Falsy`, `Blank`, and `Undef` have similar behaviour, I created
a page to demonstrate the difference and show when the user should use
one or the other.
Assisted-by: Cursor (claude-4.5-opus-high)
Since we have the ability to use `not` as a prefix, having rules that
validate negative behaviour makes them a bit inflexible, verbose, and
harder to understand.
This commit will refactor the `NotEmoji` and rename it to `Emoji`. It
will no longer check if the string contains emojis, but rather if the
string is an emoji or not. I’m also adding support to more emojis, since
the rule was a bit outdated.
This change will make the validator more strict, but will make it useful
in other scenarios. However, later on, I would like to create a rule
called `has` which, could use a validator like `Emoji` to check if the
input _has_ emojis.
Assisted-by: Cursor (claude-4.5-opus-high)
Since we have the ability to use `not` as a prefix, having rules that
start with not becomes a bit inflexible, verbose, and harder to
understand.
This commit will refactor the `NotUndef` rule by inverting its behaviour
and renaming it to `Undef`.
Since we have the ability to use `not` as a prefix, having rules that
start with not becomes a bit inflexible, verbose, and harder to
understand.
This commit will refactor the `NotBlank` rule by inverting its behaviour
and renaming it to `Blank`. Although this is a breaking change, users
will not feel it because "NotBlank" will still be available by using the
`not` prefix followed by the `Blank` rule.
We want to release version 3.0 as fresh as possible, without having to
maintain backward compatibility with the previous versions. Apart from
that, for some rules, it's impossible to be compatible with older
versions.
Acked-by: Alexandre Gomes Gaigalas <alganet@gmail.com>
Because of how the validation engine works now [1], there's no reason to
keep adding names to each rule. Instead, create a single rule that
handles naming rules with a few other accessories. This change is not
necessarily simple, but it shrinks the `Rule` interface, and it's more
aligned with how the library works right now.
Personally, I think this API is much more straightforward than the
`setName()` method, as it's way more explicit about which rule we're
naming. Because of this change, the behaviour changed slightly, but it's
for the best.
Because of this change, I managed to remove a lot of code, but
unfortunately, it's quite a big-bang commit. It would be too complicated
to make it atomic since names are an intrinsic part of the library.
[1]: 238f2d506a
Because of how the validation engine works, there's no reason to keep
adding templates to each rule. Instead, creating a single rule that
handles templating rules will simplify the library greatly and shrink
the `Rule` interface.
Personally, I think this API is much more straightforward than the
`setTemplate()` method, as it's way more explicit which rule is being
templated.
To make PHPStan recognize methods when we call Validator with static and
non-static rule names, I added a few methods from `Validator` to the
`ChainedValidator` interface[1]. However, this didn't work so well
because there could have been more methods from `Validator`.
This commit will rename the mixins to better names, but it will also
make the `Chain` (old `ChainedValidator` to have a `@mixin` on itself of
the `Validator` class.
[1]: a974c0c834
With this change, any rule can be used as a PHP attribute. I have wanted
to implement this feature for a while, as it allows you to bind the
validation to a specific property and just validate the object
afterwards.
There are a few use cases in which you would like to have a custom
exception but, at the same time, reuse the message or exception that
validation might give you.
This commit creates a new feature that allows users to define a callable
that will generate an exception when it fails.
Besides the interface's name, everything already calls this type "Rule",
not "Validatable." This commit puts a stone on it and renames the
interface for better naming.
We were not running PHPStan on those files because of the strict types
declaration. However, I decided it would be better not to have strict
types on those files than not to run PHPStan issues.
Not surprisingly, there were several issues. Some issues were impacting
how user-friendly the library is.
Since I've already renamed the "Optional" rule to "UnderOf," it makes
sense to rename this rule too.
Signed-off-by: Henrique Moody <henriquemoody@gmail.com>
This commit will rename the "Nullable" rule to "NullOr" while soft
deprecating the old name. It should work the same as the previous one
but with a different name. It will also prefix the result ID, allowing
more message customization.
While working on it, I realized that the prefix "nullOr" had a typo,
and it was using "nullOf" instead. I fixed that, too.
Signed-off-by: Henrique Moody <henriquemoody@gmail.com>
This commit will rename the "Optional" rule to"UndefOr" while soft
deprecating the old name. It should work the same as the previous one
but with a different name. It will also prefix the result ID, allowing
more message customization.
While working on it, I realized that the prefix "undefOr" had a typo,
and it was using "undefOf" instead. I fixed that, too.
Signed-off-by: Henrique Moody <henriquemoody@gmail.com>
Although helpful, the changes in the Min, Max, and Length rules made
using those rules more verbose. This commit will simplify their use by
allowing users to use them as prefixes.
Because I was creating prefixes for those rules, I made other cool
prefixes. Doing that is scary because it will generate more code to
support, and I would have liked to avoid that. However, that's a
valuable addition, and it's worth the risk.
I might reconsider that in the future, but for now, that looks like a
good idea.
Signed-off-by: Henrique Moody <henriquemoody@gmail.com>
Since we now have PHP ISO Codes as a dependency[1], it doesn't make
sense to keep dealing with this data ourselves.
[1]: 04b2722d02
Signed-off-by: Henrique Moody <henriquemoody@gmail.com>
Since we now have PHP ISO Codes as a dependency[1], it doesn't make
sense to keep dealing with this data ourselves.
[1]: 04b2722d02
Signed-off-by: Henrique Moody <henriquemoody@gmail.com>
Keeping the list of ISO 3166-2 up-to-date requires some maintenance. At
the same time, PHP ISO Codes maintains an up-to-date database with even
more ISO codes we could use in this library.
This change doesn't fully use all resources of PHP ISO Codes, but it
already removes some unnecessary code from the repository.
We've already used this library, but it was heavy because it included
all the localizations in it. Now, the package is much smaller (5.0M).
Signed-off-by: Henrique Moody <henriquemoody@gmail.com>
- For this particular updater, a list of exceptions to the rules
downloaded by geonames is included in POSTAL_CODES_EXTRA, for
cases in which we seem to do better than geonames itself based
on previous user reports.
- Added an option to also validate formatting of the postal codes.
- Combined multiple PR bots into a single one.
Previously, we were loading country info from a JSON file. This
changes it to use PHP files instead. It also caches these resources
across calls avoiding these files to be loaded more than once
per process.
We currently use a GitHub action to automate updating this file.
That action has the ability to ignore making the PR if the file
didn't changed.
Having the version number, which changed a line, was causing
several useless PR.
Users can still check if Tld.php changed by seeing the git log,
and a manual note should be issued by the maintainer on the
CHANGELOG.md file when a release containing such changes is
made.
