PHP: rfc:is-countable

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: is_countable ======
  * Version: 1.0
  * Date: 2018-01-21
  * Author: Gabriel Caruso (<carusogabriel34@gmail.com>)
  * Status: Implemented in PHP 7.3
  * First Published at: https://wiki.php.net/rfc/is-countable

===== Introduction =====

In PHP 7.2, a Warning was added while trying to ''count'' uncountable things. 
After that, everyone was forced to search and change their code, to avoid it. Usually, the following piece of code became standard:

<code php>
if (is_array($foo) || $foo instanceof Countable) {
    // $foo is countable
}
</code>


This condition, to check if a variable "is countable", is also very common in methods that return the count of the elements:

<code php>
if (is_array($foo) || $foo instanceof Countable) {
    return count($foo);
}
</code>

===== Proposal =====

This RFC proposes a new type function, that returns true if the given value is an ''array'' type or an instance of the ''Countable'' interface.

Before:

<code php>
if (is_array($foo) || $foo instanceof Countable) {
    // $foo is countable
}
</code>

After:

<code php>
if (is_countable($foo)) {
    // $foo is countable
}
</code>

======= Documentation ========

==== Description ====

  bool is_countable(mixed $var)
  
Verify that the content of a variable is an //array// or an object implementing //Countable//

==== Parameters ====

**var**
 
  The value to check
  
==== Return Values ====

Returns **TRUE** if var is countable, **FALSE** otherwise

==== Examples ====

=== Example #1: is_countable ===

<code php>
<?php
var_dump(is_countable([1, 2, 3])); // bool(true)
var_dump(is_countable(new ArrayIterator(['foo', 'bar', 'baz']))); // bool(true)
var_dump(is_countable(new ArrayIterator())); // bool(true)
var_dump(is_countable(new stdClass())); // bool(false)
</code>

=== Example #2: is_countable with conditions ===

<code php>
<?php
$foo = ['', []];

if (is_countable($foo)) {
    var_dump(count($foo)); // int(2)
}
</code>

===== Backward Incompatible Changes =====

None, as this is a new function only.

===== Proposed PHP Version =====

The next PHP 7.x, current version 7.3.

===== RFC Impact =====

This RFC has no impact on SAPIs, existing extensions, Opcache, etc.

===== Future Scope =====

Is out of scope, but a new //countable// type could be cogitated in the future.

===== Proposed Voting Choices =====

Since this is not a PHP language changed, a 50% + 1 majority is required. 

Voting begins **2018-02-26 17:00 UTC** and ends **2018-03-02 17:00 UTC**.

<doodle title="is-countable function" auth="carusogabriel" voteType="single" closed="true">
   * Yes
   * No
</doodle>

===== Proposal and Patch =====

The patch (including tests) for this proposal is available in [[https://github.com/php/php-src/pull/3026|GitHub Pull Request #3026]].

===== References =====

https://wiki.php.net/rfc/counting_non_countables\\
https://externals.io/message/101648
Page Tools
