Looking for more information on how to do PHP the right way? Check out PHP: The Right Way

SitePoint PHP Blog:
PHPBot – Can a PHP Bot Help You Look up Documentation Faster?
Aug 16, 2017 @ 10:31:39

On the SitePoint PHP blog there's a new tutorial posted from editor Bruno Skvorc looking at PHPBot, a chatbot tool that might help you look up PHP documentation questions a bit more easily (and quickly).

I came across PHPBot the other day (not to be confused with Botman or Fondbot) – a “chatbot” which helps you look up PHP manual entries and generates example code for them.

If you follow me on Twitter, you know I don’t believe in chatbots being chatbots – as someone who’s built some for both commercial purposes and personal ones, and as someone who was around in the age of IRC auto-responding scripts, I see chatbots as a little more than a marketing fad designed to impress today’s Snapchat generation. However, every now and then one will appear that’s actually useful. Could this be the one? Let’s take a look.

He starts off with some of the basic concepts behind the bot and examples of some of the output from documentation requests. He goes on to talk about the actual usefulness of the bot and provides some instances where it is still lacking in functionality. He also looks at several other subjects including Knowledgebase and Bugs, Autocompletion / Suggestion and Copy / Paste Friendliness.

tagged: phpbot documentation chatbot review feature opinion useful

Link: https://www.sitepoint.com/phpbot-can-php-bot-help-look-documentation-faster/

CloudWays Blog:
Generate Documentations For PHP Projects Through Sami
Jul 06, 2017 @ 13:47:46

On the CloudWays blog there's a new tutorial posted showing you how to create project documentation with Sami, a tool that takes the DocBlock information already in your code and makes it into something more human-readable.

Developers regularly create large blocks of code that form parts of API’s and other mid to large level projects. While there is a (more or less) agreed upon convention for code writing, every developer has a personal comment and documentation writing standards. Some add small cryptic notes while others attach full-length Google Docs that document the method or class in painful details. This problem becomes very severe when the number of end users increases and there is a need for proper documentation of the project.

[...] DocBlocks are important because they are used by a well known Symfony document generator package called Sami. Very popular in PHP community, Sami also provides the ability to create custom twig templates and work with versioned documentation on GitHub. In this article, I will use Sami and a GitHub project Sync Mysql data with Elasticsearch to automatically generate documentation.

The tutorial then helps you get the Sami package installed via Composer and how to execute it to ensure it's working as expected. Next it points you to a project to clone to help with the MySQL-to-Elasticsearch interface. It then helps with the creation of a configuration file, the results of a build and some additional tips for customizing the configuration for your environment.

tagged: tutorial documentation generation sami docblock install configure theme

Link: https://www.cloudways.com/blog/generate-documentations-for-php-projects-through-sami/

TutsPlus.com:
Programming With Yii: Generating Documentation
Jun 02, 2017 @ 11:14:03

The TutsPlus site has posted the latest article in their "Programming with Yii" tutorial series, this time covering the generation of documentation for the API code that's been created to power the application.

Recently, I wrote about building REST APIs for your Yii application and expanded custom APIs for our startup series application, Meeting Planner.

In today's tutorial, I'll introduce you to Yii's apidoc extension, which automatically generates browsable documentation for your code. I'm going to use it to generate API documentation for Meeting Planner.

The tutorial starts off with helping you get the extension installed (via Composer) and links to a few examples of the end result. The tutorial then goes through how to add your own comments to your current files that will be output in the final result directly. This includes open text descriptions and other DocBlock information. It then shows how to generate the documentation, how to navigate the resulting HTML pages and some examples of what it will look like for the current code.

tagged: programming yii2 generate documentation tutorial series package

Link: https://code.tutsplus.com/tutorials/programming-with-yii-generating-documentation--cms-27899

Symfony Blog:
The new Symfony 3.3 Service Configuration Changes Explained
May 23, 2017 @ 10:15:27

On the Symfony blog, there's an article posted by Ryan Weaver helping to explain the new service configuration changes that are included with version 3.3 of the framework.

In less than 2 weeks, Symfony 3.3 will be released. It comes with a lot of new stuff, but there is one feature that stands out: the new service configuration. I am very excited about these changes: they're designed to accelerate development, make Symfony easier to learn and encourage best-practices (e.g. injecting specific dependencies instead of using $container->get())... without sacrificing predictability and stability.

The post includes an example of what the new configuration file format will look like and briefly explains some of the changes. For those interested in a more in-depth look, they also link to this page in the Symfony documentation that goes through the changes step by step. It covers the autowiring by default, autoload of services, controllers being registered as services and more. If you're planning on making the move up to v3.3 when it's released (or sometime after) definitely check out this guide to make the transition easier.

tagged: symfony framework service configuration changes explained documentation

Link: http://symfony.com/doc/master/service_container/3.3-di-changes.html

Laravel News:
Tips For Building Your First Laravel Package
Feb 23, 2017 @ 09:42:08

On the Laravel News site there's a tutorial posted from Dmitry G. Ivanov giving you some helpful tips on building your first Laravel package.

Laravel is a powerful and modern framework. It has tons of different features, which make our work faster and easier. But you can’t push everything into the single box. At one time or another, we’ve all been in need of something not implemented in the framework out of the box.

[...] A package can be a solution. Write your code once and use it in any number of projects. Maybe you found a bug, or want to make some changes? Do it just once in your package code and then pull required changes in all of your projects. Sounds good?

The article then breaks down the information into a few different categories:

  • The First Step (checking Packagist for something pre-existing)
  • Development
  • Testing
  • Documentation
  • Release

He ends the post by pointing out that there's several other things to consider when creating your package but they're a bit more in-depth than a short post like this could tackle.

tagged: laravel package tips development documentation testing release tutorial

Link: https://laravel-news.com/first-laravel-package-tips

Mattias Noback:
Project documentation with Sculpin
Dec 12, 2016 @ 09:43:43

Matthias Noback has a recent post to his site sharing some advice and examples of how to use Sculpin for your project's documentation to make it a quick and pretty painless process.

One of the key ideas is to generate documentation instead of writing it. This should help prevent duplication and outdated information that is not trust-worthy and would therefore be neglected. I'm currently looking for ways to technically accomplish such a thing with PHP projects. This should result in reusable tools which will make it easier and more fun to document future projects while writing the code.

[...] I wanted to use Sculpin to document another project, the main project. So I started figuring out how to run Sculpin and generate a static subsite (not a blog) based on files in a subdirectory of another project. It wasn't all that hard, but I'll share the steps here anyway.

He walks you through the creation of a new Sculpin-based site and how to test and ensure it's all working correctly with simple content, a layout and configuration. He finishes out the post mentioning the themes available for Scuplin applications and links to the Bootstrap 3 theme as an example.

tagged: project documentation sculpin static generator tutorial introduction

Link: http://php-and-symfony.matthiasnoback.nl/2016/12/project-documentation-with-sculpin/

Symfony Blog:
Introducing the new Symfony Documentation
Jul 29, 2016 @ 13:47:59

On the Symfony blog there's a new post introducing the new project documentation, the result of lots of work from a large number of developers to bring the framework's documentation up to date.

When the Symfony documentation was started more than 5 years ago, it was just a few short articles written by Fabien. Now, we boast more than 1,000 pages of documentation, a team of 4 maintainers and over 1,000 contributors!

As the project grew, we've tried to innovate: adding continuous integration to catch build errors, setup Platform.sh to auto-deploy every pull request and implemented a process so that all new features to Symfony's core become documented (an amazingly rare feat).

And just like with code, a project must challenge itself continuously to stay ahead of the curve. In this article, we're thrilled to introduce the new Symfony Documentation: a result of over 150 hours of volunteer work via a secret project codenamed "Project Mercury".

They talk about some of the challenges they faced with the previous version of the documentation and some of the problems they wanted to solve. Instead of splitting things up into three sections ("Book", "Cookbook" and "Components") they opted to break it up into something more approachable for two different categories of users: "Getting Started" and "Guides" (everything else). They share some about how they made this new version happen and the workflow they followed to keep everything (and everyone) in sync.

You can check out this new documentation over on the completely revamped documentation site right now.

tagged: symfony documentation project version release update

Link: http://symfony.com/blog/introducing-the-new-symfony-documentation

Symfony Blog:
Announcing the Fourth Symfony Docs Hack Day
May 13, 2016 @ 09:58:29

On the Symfony Blog they've posted the official announcement of their Fourth Symfony Docs Hack Day happening on May 21st. This hack day is focused on just improving the documentation for the framework, not handling bugs in the main codebase itself.

The Symfony project is proud to announce its fourth Symfony Docs Hack Day. This Hack Day will be an online event to give a push to the Symfony Docs before the Symfony 3.1 release at the end of this month.

[...] Hosts Ryan Weaver, Wouter de Jong and Christian Flothmann along with you and all your friends from the Symfony community. The Hack Day is for everyone - we need Symfony experts and newcomers. If you're new to Symfony, you give us a fresh look at the documentation!

The post gives you a bit of an idea what the event will be like and what you can expect, especially as a first time submitter. It will be happening completely online via the "#symfony-docs" channel on the Freenode IRC network. You can prepare by following some of the links in the post to pending pull requests and a list of missing documentation contents.

tagged: symfony hackday documentation update event irc freenode framework

Link: http://symfony.com/blog/announcing-the-fourth-symfony-docs-hack-day

Symfony Blog:
The New Symfony Documentation Search Engine
Apr 29, 2016 @ 10:49:27

In an effort to improve their "developer experience" (DX) around using the Symfony framework the development team has introduced new searching functionality to help more effectively find what you're looking for in the expansive Symfony documentation.

Symfony boasts one of the largest documentation pools ever written for an Open- Source project. Considering the ten different Symfony versions (from 2.0 to master) and including the code samples, Symfony Documentation has around 3.6 million words, more than three times the word count of the entire Harry Potter series.

They share some of the things they learned around creating a search engine ("it's hard") and what they ultimately ended up using - the Algolia service. The post talks about how they indexed the current documentation and broke it up into "chunks" of meaningful content. They also include the simple Javascript they use that links the search field to the Algolia service and renders the results using a view partial.

The proof of concept for the new search engine was a success and we decided to stop the ElasticSearch integration and stick with Algolia. The new search engine is greatly faster than the previous one and the search results are more accurate and relevant.
tagged: symfony documentation search engine new algolia service

Link: http://symfony.com/blog/the-new-symfony-documentation-search-engine

HHVM Blog:
Improved User Documentation
Dec 15, 2015 @ 09:05:32

The HHVM blog has a post today announcing some updates they've made around the documentation for the project and the release of the "next generation" of their documentation at http://docs.hhvm.com/.

Back in August, we announced that we are going full force in revamping user documentation. We sent out a public survey to gauge the standing on the existing documentation at the time. We had 160 responses to the survey. Those results served as both validation and a guide to our approach with the new documentation.

The survey showed some interesting results including that the existing documentation could use improvement, better content in certain sections and poor examples in some places. In order to help this they worked hard to revamp the documentation and created a new GitHub repository for the docs and allows developers to pull it down locally and contribute back content/corrections as they might catch them. They also lay out the new documentation structure, breaking it up into Hack, API and HHVM sections. Finally, they talk about the technology behind the site including the runnable code examples, how they're generated and what the build process looks like.

tagged: improved documentation user hhvm hack facebook api survey results

Link: http://hhvm.com/blog/10925/improved-user-documentation