php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #73698 It's hard to find standard PHP library functions in Function Reference
Submitted: 2016-12-09 07:56 UTC Modified: 2018-06-24 16:31 UTC
From: sobak@php.net Assigned:
Status: Open Package: Documentation problem
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
Welcome back! If you're the original bug submitter, here's where you can edit the bug or add additional notes.
If you forgot your password, you can retrieve your password here.
Password:
Status:
Package:
Bug Type:
Summary:
From: sobak@php.net
New email:
PHP Version: OS:

 

 [2016-12-09 07:56 UTC] sobak@php.net
Description:
------------
Hi,

I started a non-biding discussion on /r/php regarding ways we could improve PHP Manual experience. One of complaints (which I also heard before) is that it's hard to find PHP standard library functions.

https://www.reddit.com/r/PHP/comments/5h7c5w/how_can_be_the_php_manual_improved/daz2jj8/

I think that I know the reasoning behind that. Moreover, I think is valid. There is hard to define what exactly "PHP Standard Library" is (I'm talking about SPL). One version of PHP can have `php-src/ext/calendar/` bundled and other can not. Extensions can also be excluded when compiling etc, etc.

But let's focus on `php-src/ext/standard` for now. Those are basic functions which are always available, but finding them in the manual using TOC's is rather difficult.

Let's take `file_exists()` as an example - pretty basic function.

php.net/manual/en/ (or even PHP.net -> Documentation -> English) -> Function Reference -> File System Related Extensions -> Filesystem -> Filesystem Functions -> file_exists()

Not only it's very long way to get there, I think that most of these people is lost on "File System Related Extensions". I doubt they treat `file_extists()` as any kind of an extension (once again, I do understand, why we treat it as such in terms of manual structure).

So, what I would propose is either:

1) Restructure phpdoc/reference/ to contain /standard/ directory, then divided into /strings/, /array/, /filesystem/ etc. (what exactly should be included there is another part of discussion, I think).

That sounds good, but I'm not even sure whether our current build system would allow that. It's all about xml:id's and their hierarchy, what defines our TOC's, right?

2) Don't change the hierarchy and structure at all but somehow hardcode URL's to them on top of "Function Reference". Something like:

Function Reference
- Standard library
-- Arrays
-- Filesystem
-- Strings
- Affecting PHP's Behaviour
- Audio Formats Manipulation
- Authentication Services
[...]

I'm willing to take care of implementing that, but I'd like to know opinions of more experienced Doc Team's members.


Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2018-06-24 16:31 UTC] cmb@php.net
> It's all about xml:id's and their hierarchy, what defines our
> TOC's, right?

Well, the structure is defined by manual.xml.in[1], and could be
changed (or perhaps augmented).

[1] <http://svn.php.net/viewvc/phpdoc/doc-base/trunk/manual.xml.in?view=markup>
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Thu Nov 21 19:01:29 2024 UTC