This pull request is based on (and incorporates commits from) #492.

In addition to the changes there, it presents the following:

• Clarifications to the UploadedFileInterface and ServerRequestInterface, including re-addition of getFileParams() as a canonical, non-mutable source for upload file data.
• Addition of section 1.6 to the specification, describing "Uploaded files".
• Addition of two "design decision" sections to the metadocument:
  • "Why are both getFileParams() and getUploadedFiles() present?"
  • "Why does getUploadedFiles() return objects instead of arrays?"

Another variant of PR #491 and #493 with specific return types.

This PR suggests the following changes:

• getHeader($name) takes the place of the current getHeaderLines($name) and returns an array of strings (even with only one).
• getHeaders() is unchanged and returns an array with arrays of strings for values.
• getHeaderLine($name) takes the place of the current getHeader($name) and returns a (concatenated) string.
• getHeaderLines() returns an array with strings as values.

This provides a predictable interface where the user can know the return type in advance and won't need to test whether the method returned a string or array.

It also adds consistency where both:

$message->getHeaders()[$k] === $message->getHeader($k)

And

$message->getHeaderLines()[$k] === $message->getHeaderLine($k)

This PR updates the witUri method of a request to be more explicit about its relationship to the Host header, and updates this method to perform the expected behavior of assuming the host component of the provided URI by default.

Associating a URI with a request is an abstraction on top of an HTTP message. This abstraction isn't technically required to represent an HTTP message, but it is provided in PSR-7 as a convenience for clients and servers to know more about the transport of the message (destination or source) and to more easily slice up things in the URI (path, query, etc).

One of the components of the URI is the host, and an HTTP request also has a Host header. When calling withRequest() with a URI that contains a host component the HTTP request should be updated to use the host component of the URI by default, however, there should be a way to opt out of this transformation if desired. Updating the Host header by default reflects the most common usage of an HTTP message: you typically want to send a request to the same destination as the URI you provided, and diverging from this path is atypical.

This change also simplifies the current behavior of only overriding the Host header in the request if a Host header was not explicitly set. This change removes that concept entirely. For example, all of the "softHost" stuff from Guzzle's PSR7 package would be removed and this method would be greatly simplified (and easier to use IMO): https://github.com/guzzle/psr7/blob/master/src/Request.php#L136

@weierophinney @evert

Hey,

I'd like to discuss attributes in PHP 8. Most of them will be provided by specific frameworks as soon as they will start to prepare code for PHP 8, and my goal is to have more framework-agnostic ones with explicit declared behavior.

PhpStorm already released future integration of psalm and PhpStan: https://blog.jetbrains.com/phpstorm/2020/07/phpstan-and-psalm-support-coming-to-phpstorm/ So there is no doubt such features by itself will be supported.

However, it would be cool to get away from phpdoc-annotations like @psalm-immutable to the new PHP 8 attributes, framework-agnostic ones.

In short, this PSR is about:

• @@Final('Do not inherit me unless you are ProxyManager or MockBuilder'):

  @@Final('It will be final in 5.0')
  class StreamLogger implements Logger
  {
      // ...
  }
  

  Symfony started to use such annotation (soft final) about 3 years ago for classes and methods.

  Added: probably, it requires also to add new annotation like @@Proxy to avoid issues in generated code of proxies and mocks by CI validators.

• @@Immutable (https://psalm.dev/docs/annotating_code/supported_annotations/#psalm-immutable, https://wiki.php.net/rfc/immutability);

  @@Immutable
  final class RbgColor
  {
      public function __construct(
          public int $red,
          public int $green,
          public int $blue
      ) {
          assertThat($red >= 0 && $red <= 255)
              ->that($green >= 0 && $green <= 255)
              ->that($blue >= 0 && $blue <= 255);
      }
  }
  

  This is not just best practice for value objects and similar things, but it also makes code way more readable and compact. Value objects, commands, events, DTOs, etc. No more tons of getters.

• @@ReadOnly(strict: false) (like https://psalm.dev/docs/annotating_code/supported_annotations/#psalm-readonly-and-readonly, strict is optional param that implies whether object itself can modify this value after it was set once)

  final class TokenStream implements \IteratorAggregate
  {
      @@ReadOnly(strict: false)
      public int $line;
      @@ReadOnly(strict: false)
      public int $offset;
  
      // ...
  }
  

• @@Internal('Acme\Foo') (@internal with explicit acceptable namespace; by default is just current namespace including subnamespaces):

  namespace Acme\Foo\Experimental;
  
  @@Internal('Acme\Foo')
  final class ExperimentalServiceFoo
  {
  }
  

  Class Acme\Foo\Bar is allowed to use ExperimentalServiceFoo, but classes outside of this namespace (e.g. Acme\) should not do it. Tools can help to detect incorrect usage here too.

Currently, the placement of the return type does not match that of PHP7.

For a new developer, this would seem 'wrong' as there are now 2 different signatures for methods.

In addition, allows for the documentation to support static methods that are processed by __callStatic().

And finally, this change removes the ambiguity where a method may be one of two;

<?php

class Parent
{
    public function __call()
    {

    }

    public static function __callStatic()
    {

    }
}

/**
 * @method static getString()
 */
class Child extends Parent
{
    <...>
}

Is getString() a static method returning void, or a regular method returning a static instance?

By having the scope and return type separated, the ambiguity is removed.

This PR represents the current state of affairs with the PHPDoc Standard. Until this description and subject is altered this PR is considered a Work in Progress and not ready for a final review.

All feedback is welcome, please direct this to the PHP-FIG mailing list to prevent noise in this PR. This PSR covers so many subjects that unless the discussions are separated by topic that it will probably be quite impossible to follow in this PR.

I would also request that people open a thread per issue they would like to discuss and not combine several issues in a single mail; this will help to keep noise-levels down in discussions and for me to loook back or filter important information.

TODO items are tracked in the issue tracker for this PSR: https://github.com/phpDocumentor/fig-standards/issues

You can view the rendered version at https://github.com/Seldaek/fig-standards/blob/logger-interface/proposed/logger-interface.md

The psr/log package that contains all the interfaces/classes/traits can be found at https://github.com/php-fig/log

This PR updates the description for RequestInterface::withUri(). The new description uses "MUST" in place of "will" and removes a line from the description that was inconsistent with Message::getHeaders(), getHeader(), and getHeaderLines() when the original request did not include an explicitly set Host header.

Specifically, the problematic section is:

You can opt-in to preserving the original state of the Host header by setting $preserveHost to true. When $preserveHost is set to true, the returned request will not update the Host header of the returned message -- even if the message contains no Host header. This means that a call to getHeader('Host') on the original request MUST equal the return value of a call to getHeader('Host') on the returned request.

Here's an example:

// $request1 has no explictily set Host header.
$request1->getHeader('Host'); // [] Not set, so empty array

$request2 = $request1->withUri(new Uri('http://localhost/'), true);
$request2->getHeader('Host'); // ['localhost'] Read from the URI

$request3 = $request2->withUri(new Uri('http://someotherhost/'), true);
$request3->getHeader('Host'); // ['someotherhost'] Read from the URI

I think we can drop this last sentence and avoid the inconsistency. With the stronger language ("MUST" in place of "will", etc.), the description should be clear enough.

Alternatively, we could replace the last sentence with a a more explicit explanation, but they end up being really wordy and convoluted. Something like:

You can opt-in to preserving the original state of the Host header by setting $preserveHost to true. When $preserveHost is set to true, the returned request will not update the Host header of the returned message -- even if the message contains no Host header. If a request has an explicitly set Host header, a call to getHeader('Host') on that request MUST equal the return value of a call to getHeader('Host') on the request returned by withUri() with $preserveHost set to true.

Quick Link: https://github.com/dragoonis/fig-standards/blob/master/proposed/psr-cache.md

note: the examples section in psr-cache.md will not be part of the official proposal, it is just here so that everything is under the one hood and to prove that the interfaces are solid.

Spaces The final frontier... This now supports tabs in order to fix the Internet.

Now, in all seriousness, this should be merged in order to solve the complaints on tabs vs spaces. There's one thing that it should be mentioned, there's no subversioning notice/changelog, release date/update date for the PSRs which might make updates such as this (hope it will never ever happen) noticeable by the users.

As always, the discussion is on THE MAILING LIST (look the website for it) and all comments here will be ignored.

Best regards.

This proposed PSR provides interfaces that can be used for representing HTTP messages.

This PR provides the following interfaces:

• MessageInterface
  • RequestInterface
  • ResponseInterface
• HeaderFieldValuesInterface
• StreamInterface

The motivation for each interface and the design decisions that were made can be found in the "Design Decisions" section of the document. This PR probably needs some editing and clarifications in the prose, but I think the actual interfaces are pretty well fleshed out.

Note: This pull request is a (mostly rewritten) fork of https://github.com/php-fig/fig-standards/pull/72.

• Description can exists without summary (PHPDoc rule)
• eol rule added to be compatible with PSR-12
• Summary can't be empty (summary rule)
• No spaces before tag-signature (tag-details rule)
• Fix invalid definition of keyword rule
• Description can contain line tags and can't be empty (tag-description rule)

/**
 * Render the template with the given context data.
 *
 * @param string $template
 * @param array<string, mixed> $context
 *
 * @return string
 *
 * @throw TemplateNotFoundExceptionInterface
 */
public function render(string $template, array $context = []): string;

PSR Template Renderer Proposal

A proposal for psr for rendering templates.

Goal

It is common that a library, application or CMSs need to have a template renderer / engine for rendering data for their websites or emails.

More and more application are going here to support data provider way. This application are the one which would benifit from the TemplateRendererInterface as they not only can provide them headless over an API but also make it possible that somebody can render the data via a Template Engine.

As a library author I want to make it free that my service can be used with any template engine the developer want to use. Typical usecases are PHP rendered CMSs like Sulu, Typo3, Drupal, Contao which maybe could benifit from this. But also all other data provider based libraries which ship configureable controller or have template to render like email tools / libraries.

Also for projects when somebody wants maybe switch in future from twig to latte templates as it consider better safety for xss a common interface can benifit here and avoid refractorings.

Defining the scope

The scope of the TemplateRenderer is only on rendering a given template with a given context. The template render interface will not take care of registering template paths or how to configure the template engine to find the templates. Similar how PSR-18 HttpClient does not care how the client is created or configured.

Analysis

In this section I did analyse the following existing template engines and added example how the render there templates.

• Twig (Symfony, Sulu CMS, Drupal, Contao (experimental))
• Smarty
• Latte (Nette)
• Laminas View
• Blade (Laravel)
• Fluid (Typo3)
• Contao (Contao CMS)
• Mezzio (Laminas) (already abstract Twig and Plates)
• Plates (PHP League)
• Mustache
• Yii View (Yii)

Twig

Repository: https://github.com/twigphp/Twig Current Version: v3.4.1 Supported PHP Version: >=7.2.5 Template Type Hint: string|TemplateWrapper Context Type Hint: array Return Type Hint: string or output to buffer Supports Stream: true

Render a template:

// render to variable
$content = $twig->render('test.template.twig', ['optional' => 'key-value']);

// render to output buffer
$twig->display('template.html.twig', ['optional' => 'value']);

Smarty

Repository: https://github.com/smarty-php/smarty Current Version: v4.1.1 Supported PHP Version: ^7.1 || ^8.0 Template Type Hint: string Context Type Hint: array Return Type Hint: none Supports Stream: true (only)

Render a template:

// render to output buffer
$smarty->assign('optional', 'value');
$smart->display('template.tpl');

Latte

Repository: https://github.com/nette/latte Current Version: v3.0.0 Supported PHP Version: >=8.0 <8.2 Template Type Hint: string Context Type Hint: object|mixed[] Return Type Hint: string or output to buffer Supports Stream: true

Render a template:

// render to variable
$latte->renderToString('template.latte', ['optional' => 'value']);

// render to output buffer
$latte->render('template.latte', ['optional' => 'value']);

Laminas View

Repository: https://github.com/laminas/laminas-view Current Version: ^2.20.0 Supported PHP Version: ^7.4 || ~8.0.0 || ~8.1.0 Template Type Hint: string Context Type Hint: ViewModel<null|array|Traversable|ArrayAccess> Return Type Hint: null|string Supports Stream: false

// render to variable
$viewModel = new ViewModel(['headline' => 'Example']);
$viewModel->setTemplate('index');
$content = $this->view($viewModel)->render();

Blade

Repository: https://github.com/illuminate/view Current Version: v9.15.0 Supported PHP Version: ^8.1 Template Type Hint: string Context Type Hint: array Return Type Hint: string Supports Stream: false ?

Render a template:

// render to variable
$content = view('welcome', ['name' => 'Samantha']);
// same as:
$content = $viewFactory->make($view, $data, $mergeData)->render();

Fluid

Repository: https://github.com/TYPO3/Fluid Current Version: 2.7.1 Supported PHP Version: >=5.5.0 Template Type Hint: string Context Type Hint: array Return Type Hint: string Supports Stream: false ?

// render to variable
$view = new StandaloneView();
$view->setTemplatePathAndFilename('template.html');
$view->assignMultiple(['optional' => 'key-value']);
$content = $view->render();

Contao

Repository: https://github.com/contao/core-bundle Current Version: 4.13.4 Supported PHP Version: ^7.4 || ^8.0 Template Type Hint: string Context Type Hint: object<string, mixed> via dynamic properties Return Type Hint: string Supports Stream: false ?

// render to variable
$template = new FrontendTemplate('template');
$template->optional = 'value';
$content = $template->parse();

Mezzio

Repository: https://github.com/mezzio/mezzio Current Version: 3.10.0 Supported PHP Version: ~7.4.0||~8.0.0||~8.1.0 Template Type Hint: string Context Type Hint: array|object Return Type Hint: string Supports Stream: false

// render to variable
$content = $templateRenderer->render('template', ['optional' => 'value']);

Plates

Repository: https://github.com/thephpleague/plates Current Version: v3.4.0 Supported PHP Version: ^7.0|^8.0 Template Type Hint: string Context Type Hint: array Return Type Hint: string Supports Stream: false

// render to variable
$content = $plates->render('template', ['optional' => 'value']);

Mustache

Repository: https://github.com/bobthecow/mustache.php Current Version: v2.14.1 Supported PHP Version: >=5.2.4 Template Type Hint: string Context Type Hint: array Return Type Hint: string Supports Stream: false

// render to variable
$content = $mustache->render('template', ['optional' => 'value']);

Yii View

Repository: https://github.com/yiisoft/view Current Version: 5.0.0 Supported PHP Version: ^7.4|^8.0 Template Type Hint: string Context Type Hint: array Return Type Hint: string Supports Stream: false

// render to variable
$content = $view->render('template', ['optional' => 'value']);

Spiral View

Repository: https://github.com/spiral/views Current Version: 2.13.1 Supported PHP Version: >=^7.4 Template Type Hint: string Context Type Hint: array Return Type Hint: string Supports Stream: ?

// render to variable
$content = $view->render('template', ['optional' => 'value']);

The proposal

The interface for a TemplateRender I would recommend is the following based on my analysis of exist template engines and what is the easiest way to put them together and have maximum interoperability:

/**
 * Render the template with the given context data.
 *
 * @param string $template
 * @param array<string, mixed> $context
 *
 * @return string
 *
 * @throw TemplateNotFoundExceptionInterface
 */
public function render(string $template, array $context = []): string;

For maximum compatibility we even could consider to publish 2 version of the template renderer v1 without typehints so exist template engine still supporting old php version can already implement it and v2 with typehints.

Exist TemplateRenderer Discussion

There was already an exist disussion about implementing a TemplateRendererInterface here: https://groups.google.com/g/php-fig/c/w1cugJ9DaFg/m/TPTnYY5LBgAJ.

The discussion goes over several topics just to mention the main parts:

• Template should be objects
• Context should be objects
• TemplateRender should stream to output even asynchronity

To target this specific points. I would focus in this PSR on exist solution as we see most work for template with logical string based names and do not require an object.

I want mention here also developer experience as example in the past why there was created PSR 16 (Simple Cache) where we did still have PSR 6.

So the name of the proposal should maybe be "Simple TemplateRenderer" and not try to reinventing the wheel.

By analysing exist template engine, not everybody support to have an object as a context so I would keep the interface to array for context only. This way it is easy to make exist template engine compatible with PSR interface.

For streaming the output I must say I did not see one project since 7 years which did use for example the streaming functionality of twig and for maximum compatibility I would also remove that requirement from the PSR as the analysis give there are template engines which do not support that functionality.

The proposal I did write can be found here: https://github.com/php-fig/fig-standards/pull/1280/files. I know I did skip here some process by already writing something, still I hope we can put most of the template engine creators / maintainers on one template to dicuss if they are willing to add such an interface or for which we maybe can provide a bridge, so system like CMSs, Librariy, Newsletter Tools, can make use of it. I will also bring this topic on the table for our next CMS Garden call which we have every month where several members of different CMS have a call together discussion common topics.

TODO List

• [ ] Create list which libraries would benifite using a TemplateRendererInterface and which would not
• [ ] Analyse exist Template engine of their ability to check if a template exist or not

Originally : https://github.com/php-fig/fig-standards/pull/899

Currently, the placement of the return type does not match that of PHP7.

For a new developer, this would seem 'wrong' as there are now 2 different signatures for methods.

In addition, allows for the documentation to support static methods that are processed by __callStatic().

And finally, this change removes the ambiguity where a method may be one of two;

<?php

class Parent
{
    public function __call()
    {

    }

    public static function __callStatic()
    {

    }
}

/**
 * @method static getString()
 */
class Child extends Parent
{
    <...>
}

Is getString() a static method returning void, or a regular method returning a static instance?

By having the scope and return type separated, the ambiguity is removed.

Redis recommends to use colon to namespace ours keys, and many tools use this pattern to analyse keys. So we loose much power by forbinding this.

More information there : https://github.com/symfony/symfony/issues/45599

See https://github.com/symfony/symfony/issues/44995 for details. The spec isn't extremely clear about this but all implementations I checked (very reasonably) do this already. It does not hurt to spell out the "obvious" IMO as it may not be obvious to everyone.

I am not sure if this belongs here or rather in a ML post, but anyway this is a starting point for a discussion.