The #since is used to show at what version a function was created. What if I later modify that function, should I change the #since value or do something else to show there was a change?
The basic use case for "#since" is indeed to only denote the package version when the method was first introduced.
However, since this tag's contents is really just free form text, and I'm not aware of any documentation software using for special creation of any kind of other doc elements (e.g. a report of methods group by what version introduced them), then I really see no concern with using the tag in other ways.
For example, change an original "#since 2.0 foo() introduced" to "#since 2.7 foo($arg)" to show that the API changed. I might even go so far as to use multiple tags, to show a history of the method's API:
* #since 2.0 foo() introduced
* #since 2.7 foo($arg) added the $arg argument to the signature
* #since 2.9 foo($arg = 'default') set a default for $arg
Related
I am using laravel. I need to know how phpdoc can be written in php 8 with attibutes.
/**
* Transform the resource into an array.
*
* #param \Illuminate\Http\Request $request
* #return array
*/
public function toArray($request)
{
//Some code
return [];
}
Can someone please explain how the above code can be written with attributes.
I believe you have misunderstood what Attributes are for, and how they related to doc blocks. There are two common uses of doc blocks (comments marked with /** ... */):
To document the code (hence the name "doc block"), in a mostly-standardised way which can be read by various tools, including documentation generators and IDEs.
To add machine-readable annotations to the code, for use with libraries and frameworks that can automatically generate behaviour based on those. For instance, an ORM might use an annotation of #TableName('Foo') to link a class to a particular database table, and generate appropriate SQL.
The example you've shown is of the first usage. What you have written is still the correct way of writing documentation.
PHP 8's native Attributes replace the second usage. It's up to the library what Attributes to look for, but an ORM that previously looked for #TableName('Foo') in a docblock might now look for #[TableName('Foo')] as a native Attribute instead.
There is a great automatic refractoring tool called rector. It will make your life so much easier. Install it, then create a rector.php file at the root directory that should look like something like this:
<?php
declare(strict_types=1);
use Rector\Config\RectorConfig;
use Rector\Doctrine\Set\DoctrineSetList;
use Rector\Symfony\Set\SensiolabsSetList;
use Rector\Symfony\Set\SymfonySetList;
return static function (RectorConfig $rectorConfig): void {
$rectorConfig->paths([
__DIR__ . '/src',
__DIR__ . '/tests'
]);
$rectorConfig->sets([
DoctrineSetList::ANNOTATIONS_TO_ATTRIBUTES,
SymfonySetList::ANNOTATIONS_TO_ATTRIBUTES,
SensiolabsSetList::FRAMEWORK_EXTRA_61,
]);
};
There are plenty of configuration options that you can find in the docs.
When you are done, just run the refractoring tool:
vendor/bin/rector process src
I'm running into a problem where the following email aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaanom#domaine.com is not valid according to this assertion on the Doctrine Entity using #Assert\Email for the email property.
I don't see any documentation detailing what the checks are for passing or failing this validation.
Curious to know where the code is or where I can find more documentation on what this assertion is doing...
Update, my whole assertions on that Entity property are:
/**
* #ORM\Column(type="string", length=511)
* #Filter\Trim()
* #Filter\StripNewlines()
* #Assert\NotBlank(message="email.error")
* #Assert\Email(message="email.error")
* #Assert\Length(min="6", max="150", minMessage="email.error", maxMessage="email.error")
* #Encrypted
*/
private $email;
Using Symfony 2.3
I believe Symfony\Component\Validator\Constraints\EmailValidator class is what you're looking for. Check source code
Symfony 2.3 Email validator uses the PHP var filter method
$valid = filter_var($value, FILTER_VALIDATE_EMAIL);
Which the internet leads em to believe uses similar to the following (ridiculous) regex (broken into multiple lines for readability)
^(?!(?:(?:\x22?\x5C[\x00-\x7E]\x22?)|(?:\x22?[^\x5C\x22]\x22?)){255,})(?!(?:(?:\x22?
\x5C[\x00-\x7E]\x22?)|(?:\x22?[^\x5C\x22]\x22?)){65,}#)(?:(?:[\x21\x23-\x27\x2A\x2B\
x2D\x2F-\x39\x3D\x3F\x5E-\x7E]+)|(?:\x22(?:[\x01-\x08\x0B\x0C\x0E-\x1F\x21\x23-\x5B\
x5D-\x7F]|(?:\x5C[\x00-\x7F]))*\x22))(?:\.(?:(?:[\x21\x23-\x27\x2A\x2B\x2D\x2F-\x39\
x3D\x3F\x5E-\x7E]+)|(?:\x22(?:[\x01-\x08\x0B\x0C\x0E-\x1F\x21\x23-\x5B\x5D-\x7F]|(?:
\x5C[\x00-\x7F]))*\x22)))*#(?:(?:(?!.*[^.]{64,})(?:(?:(?:xn--)?[a-z0-9]+(?:-[a-z0-9]
+)*\.){1,126}){1,}(?:(?:[a-z][a-z0-9]*)|(?:(?:xn--)[a-z0-9]+))(?:-[a-z0-9]+)*)|(?:\[
(?:(?:IPv6:(?:(?:[a-f0-9]{1,4}(?::[a-f0-9]{1,4}){7})|(?:(?!(?:.*[a-f0-9][:\]]){7,})(
?:[a-f0-9]{1,4}(?::[a-f0-9]{1,4}){0,5})?::(?:[a-f0-9]{1,4}(?::[a-f0-9]{1,4}){0,5})?)
))|(?:(?:IPv6:(?:(?:[a-f0-9]{1,4}(?::[a-f0-9]{1,4}){5}:)|(?:(?!(?:.*[a-f0-9]:){5,})(
?:[a-f0-9]{1,4}(?::[a-f0-9]{1,4}){0,3})?::(?:[a-f0-9]{1,4}(?::[a-f0-9]{1,4}){0,3}:)?
)))?(?:(?:25[0-5])|(?:2[0-4][0-9])|(?:1[0-9]{2})|(?:[1-9]?[0-9]))(?:\.(?:(?:25[0-5])
|(?:2[0-4][0-9])|(?:1[0-9]{2})|(?:[1-9]?[0-9]))){3}))\]))$
So make of that what you will.
In short, the local part of the email address is too long.
I'm not sure which part of regex decides that though.
What (if any) tag can be used to specify a create and/or last modified date for PHPDocumentor? For example:
#created 2013-01-01
#author John Doe
#updated 2013-01-06
This is primarily for file-level DocBlocks.
Old question, but I was curious if there was a standard for adding a date to a docblock and found this question.
For my particular use case, I do use code versions/versioning, but I am the solo developer on a project so only I look at my code, and as my data is date based, I like to use a #introduced yyyy-mm-dd tag in my docblocks. Nice and easy to understand and I haven't got to hunt down when a particular tag was released. My code is version controlled, so I can look at line/function history, so I never add/change the date.
/**
* A brief description of the function
*
* #introduced 2020-06-24
* #return array
*/
public funcition hello()
{
return 'world';
}
We have a page-level docblock like the following:
/**
* Functions for the processing, displaying, and searching of listings
*
* #package ListingFunctions
*
*/
The rest of the file has functions with their own docblocks. But my team and I can't find this comment anywhere in the generated HTML output. Is there some configuration or command-line stuff we need to turn on?
Using phpDocumentor 1.x, that "short description" piece should be the main description heading on the webpage for that given file. It won't appear on those functions in that file... just on the file itself. This is core behavior, that cannot be modified by runtime settings.
Some modules have a <request><direct_front_name>...</direct_front_name></request> in their module config, for example xmlconnect and api. What is this tag for?
What I think it is for:
xmlconnect and api are both used as direct entry points for the site (as opposed normal modules which are reached mostly from within the site). So in combination with the option to use store codes in your store urls you can specify a direct_front_end tag to make the store code not necessary for those modules. This way there is no 404 when calling them without a store code.
(Kind of answered it myself, but couldn't find any information about it online. Might be of use to others. And maybe anyone has something to add.)
You're totally right. And the php DOC clearly tells so :
Mage_Core_Controller_Request_Http::isDirectAccessFrontendName() :
/**
* Check if code declared as direct access frontend name
* this mean what this url can be used without store code
*
* #param string $code
* #return bool
*/
public function isDirectAccessFrontendName($code)