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';
}
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.
I have a News section in my silverstripe site and I want to use the FulltextSeach functionality of Silverstripe:
FulltextSearchable::enable();
That works fine so far. But I´d like to have only NewsPages in my result. Is there a way to filter the search so that you get only certin pageType as a result for example?
Thanks in advance,
Chris
This is untested code but I've just had a look the source code of sapphire/search/FulltextSearchable.php
in mysite/_config.php you could add:
FulltextSearchable::enable(array());
which should remove the default searched classes which are SiteTree (all pages) and File
Then you can add an object extension in mysite/_config.php:
Object::add_extension('NewsPage', "FulltextSearchable('Title,MenuTitle,Content,MetaTitle,MetaDescription,MetaKeywords')");
Below is the comments from within the FulltextSearchable.php file
/**
* Enable the default configuration of MySQL full-text searching on the given data classes.
* It can be used to limit the searched classes, but not to add your own classes.
* For this purpose, please use {#link Object::add_extension()} directly:
* <code>
* Object::add_extension('MyObject', "FulltextSearchable('MySearchableField,'MyOtherField')");
* </code>
*
* Caution: This is a wrapper method that should only be used in _config.php,
* and only be called once in your code.
*
* #param Array $searchableClasses The extension will be applied to all DataObject subclasses
* listed here. Default: {#link SiteTree} and {#link File}.
*/
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.
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