Incrementing GitHub version

PHP
#1

If I change this class constructor from this:

          public function __construct($api_key = "", $basic = false) 
          { 
                 if (!function_exists('curl_init')) 
                 { 
                        throw new CurlException("cURL is not available. This API wrapper cannot be used."); 
                 } 
              
                 if (isset($api_key))
                 {
                        $this->setApiKey($api_key);
                 } 
              
                 if ($basic === true) {
                     
                        $this->_api_key_var = 'Authorization: Basic ';
                        $this->json = false;
                 }
          }

to this one:

          public function __construct($api_key = "", $access = "") 
          { 
                 if (!function_exists('curl_init')) 
                 { 
                        throw new CurlException("cURL is not available. This API wrapper cannot be used."); 
                 } 
              
                 if (isset($api_key))
                 {
                        $this->setApiKey($api_key);
                 } 
              
                 if (strtolower($access) == "oauth") {
                     
                        $this->_api_key_var = '';
                        $this->json = false;
                        $this->accept = true;
                        
                 } elseif (strtolower($access) == "token") {
                     
                        $this->_api_key_var = 'Authorization: Basic ';
                        $this->json = false;
                 }
          }

then in GitHub and packagist should I increment minor version or major version for backward compatibility?

1 Like
#2

This is a subjective question, there isnt ‘an’ answer to it, but.
IN MY OPINION (have to put that out there, big and bold, so people don’t tell me ‘you’re wrong’),
if you’re implementing backward compatibility with a previous version, that’s a Minor version update to your code. The Major version update was when you changed the functionality in the first place.

The general rule of thumb I use is:
Minor versions are iterative,
Major versions are transformative.

#3

These two constructors are backward compatible you think?

#4

I don’t know your code.

you’re the one saying it’s being done for backward compatibility.

#5

I provided two constructors, you should be able to say if they are backward compatible or not?

#6

If you’re strictly asking me to compare the two blocks and say is one backwards compatible with the other, the answer is no - an older invoker of this will send true into the second parameter, not the string "basic"

If you want it to be backward compatible, the second parameter should be able to take a boolean true and convert it into the basic authentication flow.

#7

Let’s say I’ve imported the current version of your library and am using it like so (assuming class is called SomeClass):

$foo = new SomeClass('ABC123', true);

Now you push the new version and instead of my true meaning I want to use basic auth it doesn’t mean anything anymore, since the new version doesn’t expect a boolean there but a string.
This means that without me changing any code on my end, it broke. This is the very definition of a Backward Compatibility Break (commonly referred to as a BC Break).

So yes, you should either add a Backward Compatibility layer (accept both boolean and string and convert where needed) and mark it as minor or leave it as is and mark it as a major change.

The BC layer would look something like this:

public function __construct($api_key = "", $basic = false)
{
    $access = '';
    if (is_bool($basic) && $basic) {
        $access = 'basic';
    }

    // rest of new constructor goes here
}

Note that

  • You cannot change the name of the $basic parameter, since that would be a BC break under PHP 8
  • You cannot change the default of $basic from false to empty string, since that is also a BC break

There is a good talk by Marco Pivetta on this very subject on YouTube: Backward incompatible tales

You may also be interested in how all of this is defined in Semantic Versioning (semver): https://semver.org/

1 Like
#8

PHP 8.0 Introduced the mixed function parameter type which may be of interest:

https://php.watch/versions/8.0/mixed-type

#9

also BC break