This is an old revision of the document!
Request for Comments: docBlock Parser
- Version: 1.0
- Date: 2008-03-06
- Author: Chad Fulton ChadFulton@gmail.com
- Status: Ready for Discussion
- First Published at: http://wiki.php.net/rfc/docblockparser
Introduction
The purpose of this RFC is to propose adding functionality to Reflection which will augment Reflection::getDocComment() with a new function that will parse the DocComment string, providing a simple, standardized mechanism of retrieving metadata.
Why do we need metadata?
Metadata is data which provides additional description about a structure. In PHP, this can be used for many purposes:
- Type Information - Since PHP is a loosely typed language, there is currently no venue for encoding expected type information for use in, e.g. validation or sanitization routines.
- Relationships - In an application with many model-type classes, there almost always exist many relationships between the models that go beyond the parent-child one modeled by class inheritance. For example, the “foreign key” concept from relational databases is one such set of relationships (e.g. one-to-one, one-to-many, etc) and is important in ORM-type programs.
- Other - Unfortunately, most of the use cases fall into the “other” category, and in truth the use cases for metadata often fall into a grey area: all information contained in metadata could be contained within the structure itself. The question is whether or not it could be more elegantly and appropriately contained elsewhere.
For other use cases, see also the Annotations RFC.
Why should the PHP engine do this?
1. There is already a widely used syntax for structured DocBlocks (short description, long description, tags using the @ symbol). 2. For metadata to be the most
Common Misconceptions
RFCs do not in any way replace discussions on the mailing list.
Proposal
Nothing needs to be patched here. Just use this template at your discretion.
Rejected Features
Automated voting system.