Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:125326
Message-ID: <a0533787f9e3ad33403da7cc95f2157f4c050206.camel@ageofdream.com>
Subject: Re: [PHP-DEV] [RFC] [Discussion] Using and Mentioning Third-party
 Packages in PHP Documentation and Web Projects
To: internals@lists.php.net
Date: Tue, 27 Aug 2024 16:14:25 -0400
In-Reply-To: <663bea3c-a8e7-4881-2bcb-971a96dea9cb@php.net>
References: <642cb3ea-bf51-4832-8539-0540742000e1@app.fastmail.com>
	 <AM8P250MB0170D0B5229EC7BA2D13609FE28B2@AM8P250MB0170.EURP250.PROD.OUTLOOK.COM>
	 <663bea3c-a8e7-4881-2bcb-971a96dea9cb@php.net>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
User-Agent: Evolution 3.46.4-2 
Precedence: bulk
MIME-Version: 1.0
From: lists@ageofdream.com (Nick Lockheart)


>=20
> Just like our home page is just boring release announcements. This=20
> should have much more interesting stuff such as how, and when, to use
> the great new features that we have been adding in the last decade.
>=20

I would add that there are lots of features where the PHP manual says
how the functions work, but not how all the parts fit together.

There really should be documentation on "why do I need/want this" and
"what can I do with it"?

Reflection: When and why do we want to use this? What useful problem
does it solve and where is a working example?

Attributes: What problem does this solve and why would a developer need
this?

Fibers: When and how do we use this? And what is the exact list of
"fiberable" things? ie. Can we fiber a PDO SQL request?

And then there's stuff like SSH2, that's just a bunch of function
references, and there is no official, *complete* documentation on how
to do the entire process of connecting to a remote server over SSH,
issuing commands, checking the response of those commands (1 or 0
return value), and so on.

I think some more *tutorial* type documentation would be great from
PHP. How to put all the parts together for a complete solution to some
real world useful problem.