Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:125334
Date: Wed, 28 Aug 2024 03:51:31 -0400
To: Derick Rethans <derick@php.net>
Cc: Bob Weinand <bobwei9@hotmail.com>, Jim Winstead
 <jimw@trainedmonkey.com>, "=?utf-8?Q?internals=40lists.php.net?="
 <internals@lists.php.net>
Message-ID: <6B084580-CEFA-45A3-8221-944B9502B745@getmailspring.com>
In-Reply-To: <663bea3c-a8e7-4881-2bcb-971a96dea9cb@php.net>
References: <663bea3c-a8e7-4881-2bcb-971a96dea9cb@php.net>
Subject: Re: [PHP-DEV] [RFC] [Discussion] Using and Mentioning
 Third-party Packages in PHP Documentation and Web Projects
Precedence: bulk
MIME-Version: 1.0
Content-Type: multipart/alternative; boundary="66ced703_6b8b4567_13757"
From: john@coggeshall.org (John Coggeshall)

--66ced703_6b8b4567_13757
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline


> And that is how you will find that the "new" languages will "win". If we
> don't promote how modern PHP Development works, then there will be more
> "PHP, a fractal of bad design" articles to come for decades.
>
> We *must* do better than this. It probably doesn't all need to be in the
> documentation (doc-en), but it absolutely belongs on our website.
>

Hear Hear Derick!!
I am not advocating that php.net put its finger on the scale in favor of Laravel over others with this comment, but why php.net does not have a documentation analog similar to how Laravel's documentation is set up is beyond me. Useful installation instructions, sections on "How do I do database stuff", "Security", "Filtering Data", "Installing third party packages" etc... there are too many people who have embedded in their brains that PHP is a badly designed language because we don't teach or even advertise to people how to write good PHP code... as others have mentioned as an example, the lack of even a mention of composer on php.net is mind-blowing.
As Derick said, back 20+ years ago PHP had amazing documentation for the times -- miles ahead IMO than most open source projects. But the world has moved on, developers want and need higher level documentation that is more opinionated on not just the dry APIs available you might use to connect to a database (for example), but how to properly connect to a database. Back 20 years ago we had companies like Zend around who devoted considerable resources to filling that gap for the community (along with O'Reilly, etc.) but those entities are gone now and it is up to the project to pick up the slack.
I also think it's a mistake to get too caught up with the concept of "endorsements" and people worrying that "oh gosh if php.net talks about Laravel and Zend Framework then that means something bad for XYZ framework" (pick your favoriate techs here). It's easily solved by having a section on "Popular PHP Frameworks" that explains the concept that PHP as a language doesn't embrace any particular framework, the importance that you do generally want to embrace a framework to do anything serious, and provide a list of popular ones that people commonly turn to when building their apps. As for using a framework or any other PHP-related tech in the project's codebases... I think we're grossly overestimating how much weight that decision would carry with the PHP community at large. Short of the PHP Project stating "X is the official framework of PHP" (and especially if we say "We don't have an official framework but here are good options that are very popular" instead), the concern over the 
appearance of endorsements at this point is really an invented issue rooted at least in part by historic concerns that simply don't exist anymore.
Coogle

--66ced703_6b8b4567_13757
Content-Type: text/html; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline

<br><blockquote><div><div>And that is how you will find that the =22new=22=
 languages will =22win=22. If we</div><div>don't promote how modern PHP D=
evelopment works, then there will be more</div><div>=22PHP, a fractal of =
bad design=22 articles to come for decades.</div><br><div>We *must* do be=
tter than this. It probably doesn't all need to be in the</div><div>docum=
entation (doc-en), but it absolutely belongs on our website.</div><br></d=
iv></blockquote><div><br><div>Hear Hear Derick=21=21 </div><br><div>I am =
not advocating that <a href=3D=22php.net=22 title=3D=22php.net=22>php.net=
</a>&nbsp;put its finger on the scale in favor of Laravel over others wit=
h this comment, but why <a href=3D=22php.net=22 title=3D=22php.net=22>php=
.net</a>&nbsp;does not have a documentation analog similar to how Laravel=
's documentation is set up is beyond me. Useful installation instructions=
, sections on =22How do I do database stuff=22, =22Security=22, =22=46ilt=
ering Data=22, =22Installing third party packages=22 etc... there are too=
 many people who have embedded in their brains that PHP is a badly design=
ed language because we don't teach or even advertise to people how to wri=
te good PHP code... as others have mentioned as an example, the lack of e=
ven a mention of composer on <a href=3D=22php.net=22 title=3D=22php.net=22=
>php.net</a>&nbsp;is mind-blowing.</div><br><div>As Derick said, back 20+=
 years ago PHP had amazing documentation for the times -- miles ahead IMO=
 than most open source projects. But the world has moved on, developers w=
ant and need higher level documentation that is more opinionated on not j=
ust the dry APIs available you might use to connect to a database (for ex=
ample), but how to properly connect to a database. Back 20 years ago we h=
ad companies like Zend around who devoted considerable resources to filli=
ng that gap for the community (along with O'Reilly, etc.) but those entit=
ies are gone now and it is up to the project to pick up the slack.</div><=
br><div>I also think it's a mistake to get too caught up with the concept=
 of =22endorsements=22 and people worrying that =22oh gosh if <a href=3D=22=
php.net=22 title=3D=22php.net=22>php.net</a>&nbsp;talks about Laravel and=
 Zend =46ramework then that means something bad for XYZ framework=22 (pic=
k your favoriate techs here). It's easily solved by having a section on =22=
Popular PHP =46rameworks=22 that explains the concept that PHP as a langu=
age doesn't embrace any particular framework, the importance that you do =
generally want to embrace a framework to do anything serious, and provide=
 a list of popular ones that people commonly turn to when building their =
apps. As for using a framework or any other PHP-related tech in the proje=
ct's codebases... I think we're grossly overestimating how much weight th=
at decision would carry with the PHP community at large. Short of the PHP=
 Project stating =22X is the official framework of PHP=22 (and especially=
 if we say =22We don't have an official framework but here are good optio=
ns that are very popular=22 instead), the concern over the appearance of =
endorsements at this point is really an invented issue rooted at least in=
 part by historic concerns that simply don't exist anymore.</div><br><div=
>Coogle</div><br></div>
--66ced703_6b8b4567_13757--