Publisher Class

[MGatner]

Description
This PR introduces a new component: the Publisher Class. This combines a handful of different solutions I've been using in my modules to solve a variety of problems:

1. How do I maintain project assets with version dependencies?
2. How do I manage uploads and other "dynamic" files that need to be web accessible?
3. How can I update my project when the framework or modules change?
4. How can the framework/modules publish their modified content to a project?

Publisher has two functional modes: it can be instantiated and used dynamically with runtime input, or can use predefined workflows staged for automatic discovery. With either approach developers use fluent-style methods to build a payload manifest and then one of the "write" commands to deliver the files. For example, to inject the latest Bootstrap minimized JS & CSS files:

$publisher = new Publisher();
$publisher
	->addPath('vendor/twbs/bootstrap/dist')
	->retainPattern('*.min.*)
	->merge();

By default Publisher assumes the source is ROOTPATH and the destination is FCPATH but this can be changed with the constructor:

$publisher = new Publisher('vendor', FCPATH . 'assets/vendor/');

... or set directly on extensions:

class BootstrapPublisher extends Publisher
{
	protected $source = ROOTPATH . 'vendor/twbs/bootstrap';
	protected $destination = FCPATH . 'bootstrap/';
}

I will have lots more explanations and examples in the User Guide but I wanted to get this PR up for reviews since it has been a while since we added an entirely new component.

Note: This will need to be re-styled after the coding standards release.

A few motivations for this library:

• https://github.com/tattersoftware/codeigniter4-assets#publishing
• https://github.com/tattersoftware/codeigniter4-patches#description
• https://github.com/lonnieezell/myth-auth/blob/develop/docs/commands.md#publish
• https://github.com/paulbalandan/liaison-revision
• Refactor ComposerScripts #4634

Checklist:

• Securely signed commits
• Component(s) with PHPdocs
• Unit testing, with >80% coverage
• User guide updated
• Conforms to style guide

[MGatner]

Thanks @mostafakhudair, great clean up!

[paulbalandan]

Can we get some initial docs for this? I can't visualize this in action. 😅

[MGatner]

Oh for sure! Lots more coming, just other priorities at the moment. I'll mark this Draft so it isn't confusing.

[paulbalandan]

I think I grasp the concept and process flow. Just some comments.

[lonnieezell]

In general I like this a lot. My biggest concern is from a security standpoint. Maybe I missed it but is there anything preventing a bad package from copying files from elsewhere in the system into the public folder? Or similar dastardly deeds?

I think there has to be some way to limit the available scope of where they can work. In old versions of Bonfire I limited it to anything within the working directory for both reading and writing.

I have seen instances in other languages where a trusted package that has been around for years is taken over by another maintainer and malevolent code gets inserted which is then potentially added to many projects and developers were completely unaware. Even if they had done their homework and inspected the package nicely to begin with, after trusting it for years, you would have no reason to expect.

That's why I think we need to minimize the possibility of this at the framework level here.

[MGatner]

I had some security initially, especially around what files you could acquire from URIs, but I scrapped it after working on the discovery. We may want to think about some framework-level security or something, because the truth is at this point with our autodetection and execution this would be really easy in dozens of places (like sticking arbitrary code in a module's Config/Routes.php).

@lonnieezell like the extra attention to public/ though since anything there is web-accessible. What about denying PHP files sourced from vendor/ heading to public/? Or some similar extension-level filtering?

[lonnieezell]

Hm. This one's tricky. I can imagine typical scenarios where multiple sites are built on on instance of CI and they may have shared resources, meaning restricting this to just the web root would be problematic for those cases.

Maybe we make a white list of directories it can operate within? By default it's just the project root and any directories within that folder? Granted that makes public available but it needs to be for your example of copying bootstrap files to public. Would it be overkill to have a separate whitelist for readable and writable paths?

[MGatner]

your example of copying bootstrap files

I think this is actually the number one target use of Publisher. That's my guess at least. A lot of this was built on my Assets module whose purpose is to publish JS/CSS to web root and assist loading them. I wouldn't want to hinder that, but putting in restrictions (like filetypes) seems wise.

Would it be overkill to have a separate whitelist for readable and writable paths?

Actually I think this is a pretty good idea. Since we already have retainPattern() and removePattern() this could be very easy to implement. I'll take a shot and ask for another review.

[MGatner]

@lonnieezell I went through a few iterations of this. It's a bit of a tricky business because code executed in an auto-discovered class already technically has access to do anything it wants. I decided to focus on "what ends up where": f33d880

This introduces restrictions, which is a way of controlling the allowed destinations and types of files that can go to each destination. I've added some additional measures to make sure child classes of Publisher cannot tamper with their own restrictions to make it even more unlikely that someone's var/mail folder ends up copied into their web-accessible root.

[mostafakhudair]

With PSR-12, I think this should be reverted to bool.

[MGatner]

@mostafakhudair This whole PR will be run through CS Fixer once Paul is done with it. There are a lot of changes it will need, including the bool/boolean you noted.

[mostafakhudair]

Yeah also brackets, my fault, I didn't know that it will be auto fix, review deleted, thanks for let me know <3

[MGatner]

No worries! I appreciate your attention to detail. I noted it in the description, but it was a later edit so you probably never saw it:

Note: This will need to be re-styled after the coding standards release.

[MGatner]

I have a plan to refactor this a bit but the current PR has gotten rather cumbersome so I am going to merge it and then open a new one.