News Feed
Sections




News Archive
feed this:

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

Sammy Powers:
Contributing to the PHP Manual
June 19, 2015 @ 13:23:27

If you've wanted to contribute something back to PHP but aren't familiar with C (or don't feel comfortable enough with it) Sammy Powers offers another solution. In his latest post he shows you how to contribute to the PHP documentation and update the manual for new features, missing information or fixes to current code examples.

If you've been wanting to contribute to PHP internals, starting with the documentation can be a great entry point; especially because it doesn't require dusting off those old C books from college. But knowing where to start can be tricky since information on how to contribute to the docs is scattered across the internet. This article is a step-by-step guide of how to contribute documentation to the PHP manual.

He starts with the "quick and dirty" way of editing the manual through the edit.php.net site, but points out that it's really only useful for smaller changes, not large documentation updates. The rest of the post shows you how to set up the documentation locally and generate the results to validate your changes. He talks some about the DocBook format they're written in, the build process with the PhD (PHP docs generator) and running the php.net test suite against the changes. This ensures that nothing else has broken on the site in the process.

He shows you where to make your changes, how to generate it from either a skeleton or using the docgen script and submitting the changes back to the repository. There's also a few other random changes to make before committing the files back via SVN and pushing them back upstream. He ends the post talking about the GoPHP7-ext project and how to find extensions that are missing documentation or where it's incomplete (easy thanks to an included "check-missing-docs" file included in the repository).

0 comments voice your opinion now!
contribute documentation phpnet manual extension gophp7ext docgen tutorial

Link: https://www.sammyk.me/how-to-contribute-to-php-documentation

Laravel Podcast:
Episode 28 Documentation, JavaScript, & Conspiracy Theories
June 01, 2015 @ 10:26:50

The Laravel Podcast, with host Matt Stauffer and guests Taylor Otwell and Jeffrey Way, has posted their latest episode today: Episode 28: Documentation, JavaScript, & Conspiracy Theories.

In this episode, the crew discusses recent improvements to the Laravel documentation, Vue.js, ECMAScript 6, and a few conspiracy theories.

You can listen to this latest episode in a few different ways. You can either use the in-page audio player, download the mp3 or subscribe to their feed and get this and future episodes delivered directly to your reader of choice.

0 comments voice your opinion now!
laravel podcast ep28 documentation javascript conspiracy theory vuejs ecmascript

Link: http://www.laravelpodcast.com/episodes/12660-episode-28-documentation-javascript-conspiracy-theories

SitePoint PHP Blog:
Generating PHP Documentation with Sami
April 28, 2015 @ 09:55:31

The SitePoint PHP blog has a new tutorial posted today showing you how to generate API documentation with Sami, a "Friends of PHP" project that's currently used to generate API documentation similar to what the Symfony project provides. In this case "API" refers to your class and method structures, not something like a REST API.

Documenting your methods, classes, and functions is becoming second nature for everyone, so it makes sense to have a way to generate a separate documentation instead of navigating through the source code. In this article, I'm going to introduce you to Sami, the new API documentation generator.

He starts with a brief introduction to the DocBlock commenting methods and why you might want to choose Sami over other document generation tools (like phpDocumentor). He then helps you get Sami installed as a phar archive and how to use it to generate the document output for the Laravel Illuminate package. He includes the code you can use to set up the Sami configuration and an example of the output from the command execution. He then includes a bit about the versioning of the documentation, using themes and customizing the look and feel through custom assets and markup changes.

0 comments voice your opinion now!
sami api documentation generate tutorial symfony introduction

Link: http://www.sitepoint.com/generating-php-documentation-sami/

SitePoint PHP Blog:
Testing APIs with RAML
February 24, 2015 @ 10:19:39

The SitePoint PHP blog has a new tutorial posted today showing you how to test your API via RAML, using the structure it defines to verify the requests and responses made to the API. This is the second part of the series and you can find part one (the introduction to RAML) here.

In a recent article I looked at RESTful API Modeling Language (RAML). I provided an overview of what RAML is all about, how to write it and some of its uses. This time, I'm going to look at some of the ways in which you can use RAML for testing. We'll start by using RAML to validate responses from an API. Then we'll look at an approach you could take to mock an API server, using a RAML file to create mock HTTP responses.

He starts off by defining a basic RAML document that defines an "Albums" structure with endpoints for "account" and "albums" with various data beneath each one (and created an application that follows it). He then shows how to combine Guzzle, PHPUnit and a RAML parser to grab the API definition and set up a sample test. A simple example test is provided showing you how to check the validity of a response structure. Then he gets into mocking the API using the RAML structure using the FastRoute router. He creates a mock object and a "dispatch" method to handle the request routing based on the contents of the RAML document. He also includes a method to check the parameter values on a request, ensuring they're the correct types.

0 comments voice your opinion now!
tutorial testing unittest phpunit raml api documentation mock fastroute

Link: http://www.sitepoint.com/testing-apis-raml/

SitePoint PHP Blog:
RAML, the RESTful API Modeling Language
February 02, 2015 @ 10:52:58

The SitePoint PHP blog has a new post today introducing RAML, a modeling language made specifically for use in APIs to define services available.

n a recent article I introduced Slate, a static site generator specifically designed for writing API documentation. This time around, I'm going to look at something which in many ways is even better. But first, if you'll indulge me for just a moment, I'd like to begin by quoting myself from that article; "[an] API is only as good as its documentation." I think it's worth repeating, since it's all-too-frequently overlooked, and it's one of the motivations for this short series of articles on some of the tools out there to help you write great documentation.

RAML (RESTful API Modeling Language) provides a structured, unambiguous format for describing a RESTful API. It allows you to describe your API; the endpoints, the HTTP methods to be used for each one, any parameters and their format, what you can expect by way of a response and more.

He starts off with a few things that RAML is particularly good at helping with, including being used to generate other documentation. He then moves into writing up some of the actual RAML documentation, noting that it's a derivative of YAML and is just made from text files. He walks through the creation of a sample RAML document including the overall summary information, describing resources, HTTP methods and response structure. He also includes examples of defining query parameters, request data and any security requirements you might have. Finally, he suggests the raml2html tool if you want to generate some HTML output of your configuration, making it easier for normal humans to read.

0 comments voice your opinion now!
raml api rest modeling language documentation requirements endpoints

Link: http://www.sitepoint.com/raml-restful-api-modeling-language/

Symfony Blog:
Symfony 2014 Year in Review Symfony Documentation
December 31, 2014 @ 10:37:11

The Symfony blog has posted an update from the perspective of the documentation for the framework. Their "year in review" includes details for each section and the updates made.

2014 has been the busiest year in the entire history of the Symfony Documentation thanks to the amazing work of our documentation managers (Ryan Weaver, Christian Flothmann and Wouter De Jong) and the hundreds of documentation contributors.

They also talk about the best practices book, the new quick tour and Fabien Potencier's own How to Create Your Own Framework series. Among the list of their top ten most popular pages are the docs for:

Check out the full post for the rest of the list and what changes were made in each section.

0 comments voice your opinion now!
symfony framework documentation update yearinreview 2014

Link: http://symfony.com/blog/symfony-2014-year-in-review-symfony-documentation

Developer Drive:
Simplify your documentation process with Couscous
December 19, 2014 @ 12:14:49

On the Developer Drive site today there's a quick post introducing you to Couscous, a PHP-based documentation generation tool. Couscous translates your Markdown files into HTML output that's professional and clean looking.

If there's one thing I hate more than tracking down bugs, it's documenting code. It takes forever, it's almost a project in itself, and I never seem to factor it into my project lifecycle. Setting out to solve that problem for me, and anyone else whose life is too short, is Couscous. Couscous takes markdown files and converts them into professional standard HTML docs that colleagues, or fellow developers, can easily follow. You can preview the resulting site on your local machine, correct any issues, and then deploy straight to GitHub where it will be hosted for you.

They walk you through the (brief) process of getting the tool installed via Composer and using it to show you a preview of your documentation. The "deploy" command then allows you to easily deploy the results out to a GitHub Pages location on the gh-pages branch. You can find out more about Couscous on the project website.

0 comments voice your opinion now!
documentation couscous tool markdown generate html output

Link: http://www.developerdrive.com/2014/12/simplify-your-documentation-process-with-couscous/

SitePoint PHP Blog:
Writing API Documentation with Slate
December 15, 2014 @ 13:46:59

The SitePoint PHP blog has a new tutorial for the API developers out there showing you how you can use Slate for creating documentation. They point out a few other tools or formats you could use, but focus in on Slate, a Markdown-based tool that converts the result to HTML.

So you've built yourself an API. Perhaps it's RESTful, RESTlike or something else entirely. [...] There's one more thing, however. Thing is, an API is only as good as its documentation. That applies if it's for internal use only - perhaps it's for a JavaScript-based one-page app, or a mobile application - but even more so if it's for public consumption.

He includes an example of what the output looks like first so you know what the end result will be (and if it meets your needs). They then walk you through the installation of Slate and a few Ruby tools you'll need to generate the HTML output. He includes a simple example of the configuration and a simple document with four sections. He also shows how to use includes, alerts, tables and a sidebar. Finally he gives the "rake" command to build the documentation and how to you can push the result up to your own GitHub Pages.

0 comments voice your opinion now!
slate api documentation tutorial install configure example

Link: http://www.sitepoint.com/writing-api-documentation-slate/

Allan MacGregor:
Working with Psysh
April 14, 2014 @ 09:24:34

Allan MacGregor introduces you to Psych in his latest post today. Psysh is a runtime developer console, interactive debugger and REPL for PHP.

Psysh is actually more than a simple REPL it's also an interactive debugger; which means you can say goodbye to the endless barrage of var_dump() and die() statements. But do we really need another REPL for PHP, well honestly we could probably get by with the solutions currently available however Psysh has an extremely interesting Ace under the sleeve, it can also function as a realtime debugger.

He includes a few terminalcasts showing some of the commands Psysh offers from the expected output of variable value out to a handy link to the PHP documentation. An example of the useful object output is also included, enabling the showing of methods and properties.

0 comments voice your opinion now!
psysh repl debugger console documentation debugger

Link: http://coderoncode.com/2014/04/03/working-with-psysh.html

SitePoint PHP Blog:
Keeping Your PHP Code Well Documented
February 19, 2014 @ 10:15:19

The SitePoint PHP blog has a new post by Jacek Barecki talking about documenting your code and some suggestions for keeping this documentation useful.

Pretty much every PHP developer writes comments along with the actual code. But the language itself doesn't impose any rules on how to do so. You just have to wrap them around some specific tags and then you can write any content you want. So what exactly should be put in the comment blocks to keep them useful? Which parts of the code should be documented and which shouldn't? In this article I will present some important rules which may help you in keeping your PHP code well documented and understandable.

There's three suggestions included in the article, each with a bit of explanation and a few screenshots to illustrate:

  • Write code that explains itself
  • Keep the balance
  • Remember about the doc blocks
0 comments voice your opinion now!
documentation understandable useful tips tutorial

Link: http://www.sitepoint.com/keeping-php-code-well-documented/


Community Events

Don't see your event here?
Let us know!


series programming laravel opinion podcast framework project symfony language list api example introduction composer community application part2 interview php7 yii2

All content copyright, 2015 PHPDeveloper.org :: info@phpdeveloper.org - Powered by the Solar PHP Framework