Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:121101
Message-ID: <39d49239-c87c-2c95-c293-f2952b5e3307@bastelstu.be>
Date: Tue, 19 Sep 2023 09:30:58 +0200
MIME-Version: 1.0
To: Stephen Reay <php-lists@koalephant.com>,
 Niels Dossche <dossche.niels@gmail.com>
Cc: PHP Internals <internals@lists.php.net>
References: <c7a7f77b-8187-23f7-7c02-c92f1b538039@gmail.com>
 <c774ef73-802b-42eb-9181-9a080713c390@gmail.com>
 <CAAwdEzCQps8+cFf86-6e_7gCXtdhG7DjLTyQ3TS-=3+kW-Pcqg@mail.gmail.com>
 <29eb53a7-9aef-4e48-999e-97574f27a9df@gmail.com>
 <4C6FD028-4E34-4578-AF04-EDAC120E3E94@koalephant.com>
 <b8665e13-d317-49a0-b740-b082ec6bd2c9@gmail.com>
 <872B9392-D91A-45BC-8956-3E53B16723A6@koalephant.com>
Content-Language: en-US
In-Reply-To: <872B9392-D91A-45BC-8956-3E53B16723A6@koalephant.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
Subject: Re: [PHP-DEV] [RFC] [Discussion] DOM HTML5 parsing and serialization
 support
From: tim@bastelstu.be (=?UTF-8?Q?Tim_D=c3=bcsterhus?=)

Hi

On 9/19/23 08:35, Stephen Reay wrote:
> Regarding the private constructor: I understand the issue with the *old* class being confusing - but your new class doesn't have that issue, because there are no "loadXXX" methods: as you said, if you're loading an existing document, you're forced to do it via the static factory methods. With that change alone, there's zero risk of confusion in allowing direct constructor calls, because once the object is instantiated there is no subsequent way to load a document and inadvertently change the encoding.
> 
> Having a regular constructor and then one or more factory methods for specific cases is already a concept in PHP (i.e. DateTime[Immutable]'s  `createFromXXX` as well as a constructor), and IMO needing to call a factory method to get an "empty" document seems out of place in PHP - it seems a bit like a Java-ism - using a factory, where one just isn't required.
> 

I was one of the persons who discussed this updated API with Niels in 
private and looking up the discussion it was me who proposed making the 
constructor private and just providing named constructors.

 From the perspective of the user of the API, I like the symmetry 
between all the named constructors:

Whenever I want to create a new document, I use one of the fromXyz() 
methods. And when I use those, I get exactly what it says on the tin.

Making the regular constructor available for use would effectively make 
whatever that constructor does a special case / the default case. This 
makes sense for DateTimeImmutable, because the __construct() variant is 
likely much more often used than the various createFromXyz() variants. 
For the HtmlDocument I find it less obvious that creating an empty 
document would be the default case compared to loading an existing 
document from a file.

We should probably rename the named constructors to include the "create" 
prefix for consistency with DTI though.

Best regards
Tim Düsterhus