rfc:batch_use_declarations

# Differences

This shows you the differences between two versions of the page.

 rfc:batch_use_declarations [2015/01/29 23:14]marcio change feature name to "group use declarations" rfc:batch_use_declarations [2017/09/22 13:28] (current) Both sides previous revision Previous revision 2015/01/29 23:16 marcio moved page2015/01/29 23:14 marcio change feature name to "group use declarations"2015/01/29 22:51 marcio accept Danack's suggestions 2015/01/29 16:31 marcio fix some code samples that had duplicated use statements2015/01/29 16:29 marcio remove the "AST decoration" mumble jumble since with the patch doesn't work this way anymore.2015/01/29 05:51 marcio add reference links to source code claimed to be real world examples2015/01/29 05:13 marcio update RFC to reflect latest patch; clarify use function and use const usage.2015/01/28 22:56 marcio 2015/01/28 22:46 marcio 2015/01/28 22:07 marcio typo2015/01/28 22:02 marcio add patch entry to RFC header2015/01/28 21:41 marcio created Next revision Previous revision 2015/01/29 23:16 marcio moved page2015/01/29 23:14 marcio change feature name to "group use declarations"2015/01/29 22:51 marcio accept Danack's suggestions 2015/01/29 16:31 marcio fix some code samples that had duplicated use statements2015/01/29 16:29 marcio remove the "AST decoration" mumble jumble since with the patch doesn't work this way anymore.2015/01/29 05:51 marcio add reference links to source code claimed to be real world examples2015/01/29 05:13 marcio update RFC to reflect latest patch; clarify use function and use const usage.2015/01/28 22:56 marcio 2015/01/28 22:46 marcio 2015/01/28 22:07 marcio typo2015/01/28 22:02 marcio add patch entry to RFC header2015/01/28 21:41 marcio created Line 1: Line 1: - ====== PHP RFC: Group Use Declarations ====== + Moved to https://​wiki.php.net/​rfc/​group_use_declarations - * Date: 2015-01-28 + - * Author: Márcio Almada, marcio.web2@gmail.com + - * Status: Draft + - * First Published at: http://​wiki.php.net/​rfc/​group_use_declarations + - * Patch: https://​github.com/​php/​php-src/​pull/​1005 + - + - ===== Introduction ===== + - This RFC represents an attempt to improve current PHP namespace implementation by introducing the concept of **Group Use Declarations**:​ + - + - + - // Proposed group use syntax: + - + - use FooLibrary\Bar\Baz\Biz { ClassA, ClassB, ClassC as Fizbo, ClassD }; + - + - // Compared to current use syntax: + - + - use FooLibrary\Bar\Baz\Biz\ClassA;​ + - use FooLibrary\Bar\Baz\Biz\ClassB;​ + - use FooLibrary\Bar\Baz\Biz\ClassC as Fizbo; + - use FooLibrary\Bar\Baz\Biz\ClassD;​ + - ​ + - + - ===== Proposal ===== + - Group use declarations,​ also known as **grouped imports**, are just **syntax sugar** to cut verbosity when importing multiple entities from a common namespace. Using common PHP library examples, the following use declarations are equivalents:​ + - + - + - // Current use syntax: + - + - use Doctrine\Common\Collections\Expr\Comparison;​ + - use Doctrine\Common\Collections\Expr\Value;​ + - use Doctrine\Common\Collections\Expr\CompositeExpression;​ + - + - // Proposed group use syntax: + - + - use Doctrine\Common\Collections\Expr { Comparison, Value, CompositeExpression }; + - ​ + - + - === Compound Namespaces === + - Compound namespaces are also allowed. For instance, the following use declarations are equivalents:​ + - + - + - // Current use syntax: + - + - use Symfony\Component\Console\Helper\Table;​ + - use Symfony\Component\Console\Input\ArrayInput;​ + - use Symfony\Component\Console\Output\NullOutput;​ + - use Symfony\Component\Console\Question\Question;​ + - use Symfony\Component\Console\Input\InputInterface;​ + - use Symfony\Component\Console\Output\OutputInterface;​ + - use Symfony\Component\Console\Question\ChoiceQuestion as Choice; + - use Symfony\Component\Console\Question\ConfirmationQuestion;​ + - + - // Proposed group use syntax: + - + - use Symfony\Component\Console { + - Helper\Table,​ + - Input\ArrayInput,​ + - Input\InputInterface,​ + - Output\NullOutput,​ + - Output\OutputInterface,​ + - Question\Question,​ + - Question\ChoiceQuestion as Choice, + - Question\ConfirmationQuestion,​ + - }; + - ​ + - + - This is also a real use case. Check out the Laravel source code: + - + - * [[https://​github.com/​laravel/​framework/​blob/​5afdac39290bc38d729830190f17581b60b08502/​src/​Illuminate/​Console/​Command.php#​L3-L10|https://​github.com/​laravel/​framework/​blob/​4.2/​src/​Illuminate/​Console/​Command.php#​L3-L10]] + - * [[https://​github.com/​laravel/​framework/​blob/​5afdac39290bc38d729830190f17581b60b08502/​src/​Illuminate/​Log/​Writer.php#​L5-L9|https://​github.com/​laravel/​framework/​blob/​4.2/​src/​Illuminate/​Log/​Writer.php#​L5-L9]] + - + - === Non Mixed Use Declarations === + - As expected, non mixed group use declarations are supported:​ + - + - + - // Current use syntax: + - + - use function foo\math\sin,​ foo\math\cos,​ foo\math\cosh;​ + - use const foo\math\PI,​ foo\math\E, foo\math\GAMMA,​ foo\math\GOLDEN_RATIO;​ + - + - // Proposed non mixed group use syntax: + - + - use function foo\math { sin, cos, cosh }; + - use const foo\math { PI, E, GAMMA, GOLDEN_RATIO }; + - ​ + - + - === Mixed Use Declarations === + - + - The current implementation of namespaces does not allow mixed imports of functions, constants and classes. The proposed implementation would allow mixed imports like this: + - + - Current namespace implementation does not allow mixed imports of functions, constants and classes. The proposed implementation would allow mixed imports like this: + - + - + - // Current use syntax: + - + - use foo\math\Math;​ + - use const foo\math\PI;​ + - use function foo\math\sin,​ foo\math\cos,​ foo\math\cosh;​ + - + - // Proposed mixed group use syntax: + - + - use foo\math { Math, const PI, function sin, function cos, function cosh }; + - + - ​ + - + - ===== Justification ===== + - + - Group use statements makes it easier to identify that multiple imported entities are from the same module. For the first example in this RFC, instead of having to read '​FooLibrary\Bar\Baz\Biz'​ four times to see that the namespace is the same for each entry, it is clear by the grouping syntax that the entries all come from the same namespace. + - + - Also, group use statements makes it easier to see in patch diffs that a dependency on a new module has been introduced. For instance, a patch that adds a new dependency on "​Consolidation"​ namespace has been introduced:​ + - + - <​code>​ + - use Symfony\Component\Console\Question\ConfirmationQuestion;​ + - use Symfony\Component\Console\Question\ChoiceQuestion as Choice; + - +use Symfony\Component\Console\Question\OptionQuestion;​ + - +use Symfony\Component\Consolidation\Question\OptionQuestion;​ + - use Symfony\Component\Console\Question\Question;​ + - ​ + - + - With the current use syntax it's necessary to read to the 30th character of the 2nd modified line to realise that the patch adds a new dependency. The proposed syntax is much more readable: + - + - <​code>​ + - use Symfony\Component\Console\Question { + - ConfirmationQuestion,​ + - ChoiceQuestion as Choice; + - +   ​OptionQuestion,​ + - Question, + - }; + - +use Symfony\Component\Consolidation\Question\OptionQuestion;​ + - ​ + - + - + - ===== About The Syntax Choice ===== + - The syntax chosen is inline with the current trait adaptation syntax to make it look and feel similar to existing PHP standards. Such design choice allows the feature to stay familiar and intuitive to most PHP user base. + - + - ===== Optional: Nested Group Use Declarations ===== + - **Nesting** would allow the following use case: + - + - + - use Symfony\Component\Console { + - Helper\Table,​ + - Input { ArrayInput, InputInterface } + - Output { NullOutput, OutputInterface }, + - Question { Question, ChoiceQuestion,​ ConfirmationQuestion } + - }; + - ​ + - + - As the author of this RFC, I consider the **nesting** option **too complex** to be introduced. But since many people mentioned this **possibility**,​ it will be put into the discussion so the community has a chance to appoint. + - + - ===== Backward Incompatible Changes ===== + - There is no BC breaks with current implementation or feature concepts. + - + - ===== Proposed PHP Version(s) ===== + - This is proposed for the next PHP x, which at the time of this writing would be PHP 7. + - + - ===== RFC Impact ===== + - + - === On Backward Compatibility === + - This RFC is backwards compatible with previous PHP releases. + - + - ===== Open Issues ===== + - * Should nested group use declarations be allowed? + - + - ===== Unaffected PHP Functionality ===== + - Original namespace implementation is not affected by the addition of group use declarations. Current syntax would still be valid. + - + - ===== Proposed Voting Choices ===== + - As this RFC represents a language change a two third majority is required. + - + - ===== Patches and Tests ===== + - The implementation aims to be minimal and of easy maintenance. I created a PR so that the patch diff can be viewed easily: https://​github.com/​php/​php-src/​pull/​1005 + - + - The current initial implementation can be found on my PHP [[https://​github.com/​marcioAlmada/​php-src/​tree/​group-use|fork]]. You can also directly contribute to this RFC by sending a pull request to https://​github.com/​marcioAlmada/​RFCs. + - + - ===== References ===== + - There is no found record related to group use declarations on mailing lists. + - + - ==== Support in other languages ==== + - Other languages have similar ways to import multiple entities from a given package or module: + - + - * [[http://​www.rust-lang.org|Rust Language]] has a very similar sintax use a::​b::​{c,​d,​e,​f};​ + - * [[https://​www.python.org|Pyhon]] has a different syntax but with the same objective: from fibo import fib, fib2, fib3 + - + - ===== Rejected Features ===== + - Awaiting discussion. +