Add .gitattributes to exclude dev files from Composer package

[Krinkle]

This omits unnececary files from the deployed package. Especially when auditing packages for production deployment, or when versioning the vendor/ directory, this helps reduce noise.

This package is currently being considered for bundling with https://github.com/Wikipedia/mediawiki (vendor). The extraneous files from Net_URL2 stood out in a local build as most other packages seem to exclude these kinds of files.

[ktomk]

@Krinkle Looks very fine on first glance.

By the type of change I get somewhat the impression that this is not only for this specific package. So could you add a bit of context to this PR why each directory has been chosen? Especially if this is about Net_URL2 only or is more in the general structure of Pear package projects?

[Krinkle]

@ktomk Indeed, this is not specific to the Net_URL2 package, and not even specific to Pear projects.

Most dependencies that Wikipedia uses via Composer seem to make their exports relatively minimal and are at least loosely aware of how Packagist exports it from Git.

For Pear projects, I suspect this has not been taken to account simply because it isn't (historically) the main way these projects are distributed. So even if it was considered, it will have likely been expressed somewhere other than in .gitattributes.

This is the first Pear dependency that Wikipedia loads via Composer (we've previously loaded one or two by other means), and thus the first time I noticed it.

[ktomk]

@Krinkle Thanks for your response on the topic. Based on your reply I've taken the opportunity to review the changes. I think they are fine for production code-only distribution especially in context of distributing via composer and prefer-dist with Github repositories.

Would you be so kind and could leave some feedback about how the overall experience is to make use of this library via composer? I ask because from what I remember when the package was ported over to Github some years ago and when adding composer support, IIRC it was needed to add the include-path setting in composer.json. This is normally not that well. But I also see there is classmap autoloading:

    "autoload": {
        "classmap": ["Net/URL2.php"]
    },
    "include-path": [
        "./"
    ],

So I'm interested if this has any implications for your use-case next to the export improvements already done.

[Krinkle]

As someone who uses Composer, the presence of include-path here stands out as "odd". I suppose maybe it is here to simplify migration for legacy apps that previously installed the package from from PECL (without a class loader). These users would presumably have placed statements like require_once "Net/URL2.php.php" anywhere in their code, and based on the PHP include_path it would eventually find this directory file and load the class file that way.

In the Composer landscape, I believe it is generally preferred not to rely on internal file paths or run-time directory scanning of this kind, in favour of mapping a namespace to a directory (PSR-4). Alternatively, you can also give it a list of files and directories and let it scan these are install-time and builds its own class-to-file map. The latter is what NET_URL2 currently uses.

This means that during installation, composer finds the URL2.php file, finds that it declares the NET_URL2 class and memorises this for itself (example).

For the majority of existing and for all new users, I would expect include-path therefor to be redundant. But it's up to you whether to continue to support that. If you want to remove it, all you'd have to do is remove include-path and then for end-users they would simply have to remove any stray require or include statements for NET/URL2 from their code. They would not have to put anything in its place, because they are already using Composer and that is already registering Net_URL2 with PHP's autoloader, which means they can reference the class directly in their code without any such require or include statement.

See https://getcomposer.org/doc/04-schema.md#autoload for more information.

Hope that helps!