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

Laravel News:
Navigating a New Laravel Codebase
Mar 07, 2018 @ 11:57:50

For those out there that are new to using the Laravel framework and are a bit lost in trying to figure out its structure, Laravel News has just the article for you. In this new tutorial they give you an overview of the Laravel codebase and how you should structure your applications to keep everything organized.

Getting started in a new codebase can be very overwhelming, even more so if you are new to programming. So where do you start? Where are the places to look to learn the most about a codebase? Let’s take a look at few common areas for Laravel.

They start by talking about project documentation and how it can play a vital role in the on-boarding of developers new to the application. From there the post goes on to talk about the composer.json configuration, route configurations, service providers, tests and some additional tooling. For each item there's a paragraph or two explaining its place in a Laravel application and, in some cases, links to other resources for more information.

tagged: laravel codebase navigate documentation composer serviceprovider test tool route

Link: https://laravel-news.com/navigating-a-new-laravel-codebase

Laravel News:
TLDR Pages: Simplified and Community-Driven Man pages
Dec 05, 2017 @ 09:28:13

On the Laravel News site today they've posted about an effort that's been started to help create simple and community-driven man pages (documentation, manual pages) for command-line tools.

The TLDR pages (too long; didn’t read) is a command-line project that aims to simplify man pages with useful, terse examples of commands. This CLI tool gives me even less reason to memorize the tar and curl flags.

The way the TLDR command works after you’ve installed it is by passing it a command for which you’d like to learn practical uses without combing the full manual.

The article shows how to install this tldr package via npm and make it global on your system to be able to use it anywhere. There are also options for other languages if Node.js isn't your thing. You can find out more about the tool and what features it offers over on the project homepage. They also link to the repository if you'd like to contribute back to the documentation.

tagged: tldr toolongdidntread manual page documentation community project install

Link: https://laravel-news.com/tldr-pages

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