feat: add integration with Mezzio

[DominicDetta]

This pull request allow to use Clockwork in Mezzio application.

[UlrichEckhardt]

I'm not the maintainer, so just a few non-normative comments:

• Why did you derive from Clockwork\Support\Vanilla\Clockwork? First off, the additional utility functions (isEnabled() in particular) are really useful additions, but I'd just put them into the baseclass. Then, only the constructor remains, where I find it's really bad practice to not invoke parent::__construct(). I think, just using the enhanced vanilla baseclass would work just as well, so that class and config.php can go.
• I think the routing bits in the middleware are not complete yet. There is the /latest, a placeholder for the newest record, and there is /<ID>/extended, which retrieves full info (in particular the XDebug profiler data) from the according data sources.

That said, cool contribution! I personally don't use Mezzio, but open source lives from participation!

[DominicDetta]

Thank you for your fast response.
I derived from Clockwork\Support\Vanilla\Clockwork because I want to be able to use all built-in functions but the only down-side was that the original config.php was using the $_ENV which I replaced it with a cross-compatible function getenv. In this way I guarantee that works in any environment. Furthemore I didnt invoke the parent::__construct() because some application could configure Clockwork directly using environment variables without passing any PHP configuration.
I didnt want to modify the base class but if approved I can move all utility functions to it.
I verified and the /latest works correctly. I will try the other missing routing.

[DominicDetta]

I solve the parent__construct() issue as desired.

[DominicDetta]

Do you know if the project is using the PSR-12 as formatter?
The class Clockwork\Support\Vanilla\Clockwork is completely changed

[DominicDetta]

I tested also the the routing for /extended and it works perfectly.

[UlrichEckhardt]

Clockwork seems to use tabs to indent the code. If your IDE autoformatted the files with four-space indent (which is the default per PSR, I believe), then it breaks the formatting here.

[itsgoingd]

Hey, thanks for working on this.

Would you be interested in releasing this integration on your own as a separate package, with me linking it in the official Clockwork readme/website?

Could you please fix the indentation to use tabs? Otherwise the diffs are impossible to read. Also, what is the meaningful difference between using $_ENV and getenv?

[DominicDetta]

Yes, I can create a separate package.

The difference between $_ENV and getenv is obscure to me as well but from my experience in a docker environment with Apache the environment variables are not returned when using $_ENV.

[UlrichEckhardt]

https://stackoverflow.com/questions/8798294/getenv-vs-env-in-php has some info on that...

[UlrichEckhardt]

https://stackoverflow.com/questions/3780866/why-is-my-env-empty may be even better. With that in mind, I'd vote for using getenv() exclusively and not using the volatile $_ENV. That would be a change for the the Vanilla integration though, not just for Mezzio.

[DominicDetta]

It would be preferrable to integrate this PR and avoid to create a separate package as it would be additional installation which would make this project interesting for those who use microframework Mezzio which is a project of Laminas

[DominicDetta]

To make the integration with clockwork more interesting, may I add that I have the intention of requesting an amendment to Mezzio's documentation

[UlrichEckhardt]

I believe this is what CLOCKWORK_WEB_URI is supposed to be.

[DominicDetta]

As explained by the documentation to serve the WEB UI you need to specify this routing:

$router->get('/clockwork', function ($request) {
     $clockwork = Clockwork\Support\Vanilla\Clockwork::init([
         'web' => [
             'enable' => true,
             'path' => DIR . '/public/vendor/clockwork',
             'uri' => '/vendor/clockwork'
         ]
     ]);
 
     return $clockwork->usePsrMessage($request, new Response)->returnWeb();
}};

In this case /clockwork represents the url path to the server-side request and it's different from the web uri parameter. Did I miss something? I created a new variable web host to be able to configure the server-side request url path.

[itsgoingd]

The Web UI in the Vanilla integration works in a bit of a funny way. It actually copies the Web UI implementation to a public directory, so the assets are served directly by the web server, this is by default public/vendor/clockwork. The code handling the main web UI route, typically /clockwork, then returns a special full-screen iframe that embeds the Web UI located at /vendor/clockwork with some special configuration to make it work.

[UlrichEckhardt]

This is something that is not really clear and I believe that the different integrations differ a bit, too. Just for reference, here are the two settings I found:

		// Path where to install the Web UI assets, should be publicly accessible
		'path' => isset($_ENV['CLOCKWORK_WEB_PATH']) ? $_ENV['CLOCKWORK_WEB_PATH'] : __DIR__ . '/../../../../../public/vendor/clockwork',

		// Public URI where the installed Web UI assets will be accessible
		'uri' => isset($_ENV['CLOCKWORK_WEB_URI']) ? $_ENV['CLOCKWORK_WEB_URI'] : '/vendor/clockwork'

Note that both are commented with the words "accessible" and "public" and both contain a path, which is a bit confusing.

Anyhow, just out of interest, why does the web UI copy the files between paths? I've use the Web class' assets and served them from where they are for my PSR-based middleware implementation.

[DominicDetta]

@itsgoingd

The Web UI in the Vanilla integration works in a bit of a funny way. It actually copies the Web UI implementation to a public directory, so the assets are served directly by the web server, this is by default public/vendor/clockwork. The code handling the main web UI route, typically /clockwork, then returns a special full-screen iframe that embeds the Web UI located at /vendor/clockwork with some special configuration to make it work.

This is exactly how I understood when using it. I only added a new env vars CLOCKWORK_WEB_HOST to configure the /clockwork url but if you think it's useless I can hadcode the url in the middleware and remove it.

[UlrichEckhardt]

Just wondering, does Mezzio come with a PSR-17 response factory, included or as dependency? Point is, using PSR-7, PSR-15 and PSR-17 as base, I think I could build a middleware that can be integrated into pretty much any framework that uses those HTTP PSRs, including Slim (which is my concern) and Mezzio.

[DominicDetta]

When you install Mezzio from the skeleton provided the dependency laminas-diactoros is installed which implement PSR-7 and PSR-17.

[DominicDetta]

Right now my middleware use the Laminas\Diactoros\Response. If there is a way to create a response without relying to it, it will be completely framework agnostic.

[itsgoingd]

@UlrichEckhardt I was actually thinking the other day, why do we still need a custom Slim integration, when the Vanilla integration is superior and more full-featured. I think it would be a really good idea to add a generic PSR-compatible middleware to the Vanilla integration as you suggest.

@DominicDetta I think I would put this on hold and explore the route of adding a generic middleware to support all these PSR-compatible micro-frameworks first.

Also, I'm okay with changing the Vanilla config file to use getenv, if anyone wants to make that PR.

[UlrichEckhardt]

https://github.com/UlrichEckhardt/clockwork-slim-demo/tree/feature/psr-17-middleware -- Slim doesn't need a custom integration, it provides implementations for the PSR-{7,15,17} interfaces, so it could use any middleware built on top of that. I've realized that in the above demo project, which should be seen as a proof of concept.

There's still a few things to do:

• Middleware needs to be integrated into the clockwork sources, consistently formatted with tabs.
• The configuration access methods need to be integrated into the Support\Vanilla\Clockwork class.
• The web path needs to be clarified.
• Documentation.
• Testing. ;)

[DominicDetta]

@DominicDetta I think I would put this on hold and explore the route of adding a generic middleware to support all these PSR-compatible micro-frameworks first.

Ok, that sounds right.

[UlrichEckhardt]

I just added #680, including two demo projects for both Slim and Mezzio. This is still in draft form, in particular there are still a few places marked TODO: ... that need work. Still, it's working and something to toy with.

[DominicDetta]

This PR will be replaced by #680