Documentation?

[adriansuter]

Unfortunately I have not found a documentation nor any best-practices on how to use this library with slim 4. The README explains the instantiation process only.

In a test installation I used it in the route callable (an invokable class) the following way - is that correct?

// .... strict types and namespace

use Slim\Http\Response;
use Slim\Http\ServerRequest;

class HomeController
{
    public function __invoke(ServerRequest $request, Response $response, array $args = []): Response
    {
        return $response->withJson(['foo' => 'bar']);
    }
}

Am I loosing anything by directly typehinting Slim\Http\ServerRequest and Slim\Http\Response for the first two params?

The documentarion should mention that after installation (which works out-of-the-box), the first two arguments of the route callables would be decorated. I assume the same holds for the middleware $request param and for $response in the middleware code $response = $handler->handle($request);.

[l0gicgate]

You are never losing anything. Your application is however dependent on those objects though. It's not that complicated to change later though if you wanted to get rid of it.

I'm not sure how to go about docs right now. Do we include it on the Slim-Website under the regular docs in its own section? or do we create an entire new website.. It is a package that can be used with other PSR-7 implementations so it can stand alone.

[adriansuter]

I suggest to write a documentation of its own. Always under the assumption, that this package can be used with other PSR-7 implementations.

And in the Slim 4 docs, I would add a section that shows how to use this package explicitly together with Slim. I think that the decorator "Slim-Http" would be used by most people. So it could probably be a sub-section in the Concepts section? Maybe after PSR-7?

However, the section does not have to contain or describe all non PSR-7 methods. I would add a link to the Slim-Http docs though, where a complete reference of all extra methods can be found.

[adriansuter]

How about using github pages and one of its predefined themes in order to create the docs? Maybe such that these pages would be accessible via http://http.slimframework.com? Or do you think that the docs for this "library" should be in the same look as the slim docs?

[bennnjamin]

I was trying to upgrade a Slim 3 application to Slim 4 which is strictly a JSON API and I had to find this issue to figure out that the HTTP decorators were not working for parsing the body and creating a JSON response because the Route Controller needed:

use Slim\Http\Response;
use Slim\Http\ServerRequest;

Part of the confusion was from following this https://github.com/slimphp/Slim#hello-world-using-appfactory-with-psr-7-auto-detection where I assumed all routes needed:

use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;

If had I done nothing it would have worked. Perhaps in the upgrade guide for v3 to v4 there should be a section on preserving Slim 3 behavior by installing this repo and a PSR-7 implementation. Or the documentation for using this repo with Slim 4 could be under the Cookbooks section of the current documentation site and standalone usage documentation should be in this repo.