Какие типы значения может вернуть функция инструкцией return php

Return types in PHP refer to the type of data returned by a function in PHP. In strongly typed languages like JAVA, every function must have a return type but it is optional in PHP as it is a loosely typed programming language. It is a good practice to include return types as it reduces ambiguity, limits error and improves code quality.

We will be looking into several return types in PHP. Without any further ado, let’s dive in.

Prerequisite

• PHP version 8

• Basic knowledge of PHP

To enforce return type in PHP functions, we need to include a simple declaration at the top of the file.

declare(strict_types=1);

This is a PHP directive that enforces strict typing. It is used to ensure that only values of the expected data type are passed to a function or method.

When strict_types is set to 1, PHP will require that function arguments are of the correct data type. If an argument is of the wrong type, PHP will throw a TypeError instead of attempting to convert the argument to the expected type.

With this in place, we can be rest assured PHP is not doing any type conversion that we may not be aware of when incorrect types are used.

The type of data we want the function or method to return is declared by putting a colon and the type between the closing parenthesis and the opening curly bracket.

int

int return type represents integers in PHP. They are positive or negative whole numbers without decimals, int can also be zero.

function addition(int $a, int $b): int {
  $sum  = $a + $b;
  return $sum;
}

echo addition(12, 20);

In class example:

class Arithmetic {
  public function __construct(public int $a, public  int $b) {}

  public function addition(): int {
    $sum = $this->a + $this->b;
    return $sum;
  }
}

echo (new Arithmetic(12, 20))->addition();

string

The string is a return type used to represent text. It can contain any sequence of characters, including letters, numbers, symbols, and whitespace.

Strings can be declared using a single or double quote.

function greeting(): string {
 return "Good day fellow!";
}

echo greeting();

class Greeting {
  public function __construct(public string $message) {}

  public function greeting(): string {
    return $this->message;
  }
}

echo (new Greeting("Good day fellow!"))->greeting();

float

Float is a return type used to represent numbers with a decimal point. Floats are also known as «floating point numbers» or «doubles».

function price(): float {
  return 10.56;
}

echo price();

class Socks {
  public function price(): float {
    return 10.56;
  }
}

(new Socks())->price();

Floats can be negatives too.

function price(): float {
  return -1.78;
}

echo price();

class Socks {
  public function price(): float {
    return -1.78;
  }
}

(new Socks())->price();

bool

bool, short for «boolean», is a return type used to represent logical values. A bool variable can only have two possible values: true or false.

It is important to note that PHP returns 1 for true and nothing for false.

function isComplete(): bool {
  return true;
}

echo isComplete();


function isAdult(int $age): bool {
  return $age >= 18;
}

echo isAdult(10);

class Task {
  public function isComplete(): bool {
    return true;
  }
}

class Person {
   public function isAdult(int $age): bool {
    return $age >= 18;
  }
}

echo (new Task)->isComplete();
echo (new Person)->isAdult(2);

array

The array is a return used when a method or function is expected to return an array. PHP has index, associative and multidimensional arrays, any of these can be returned when an array return value is used.

function playlist(): array {
  return ['Diced Pineapple', 'Formation', 'Thinking Out Loud'];
}

print_r(playlist());

function user(): array {
  return ['name' => 'John', 'age' => 25, 'location' => 'New York'];
}

print_r(user());

class Playlist {
  public function music(): array {
    return ['Diced Pineapple', 'Formation', 'Thinking Out Loud'];
  }

  public function user(): array {
    return ['name' => 'John', 'age' => 25, 'location' => 'New York'];
  }
}

print_r(
  (new Playlist)->music()
);

print_r(
  (new Playlist)->user()
);

void

In the case we do not wish to return anything, the void is the goto return type. It simply means nothing will be returned.

function earth(): void {
  $title = "This planet supports life";
  $age_in_years = 4_800_000_000;
}

earth();

class Planet {
  public function earth(): void {
    $title = "This planet supports life";
    $age_in_years = 4_800_000_000;
  }
}

(new Planet)->earth();

mixed

A mixed return type is used to indicate that a function or method may return different data types, depending on the input or the logic within the function. This is helpful when you cannot determine the exact return type ahead of time, or when the return type is dependent on a complex set of conditions.

function randomType(): mixed {

    $value;

    switch(rand(1, 5)) {

      case 1: $value = "Good day fellow!";
      break;
      case 2: $value = 10.22;
      break;
      case 3: $value = true;
      break;
      case 4: $value = ['Sport', 'Movies'];
      break;
      default: $value = 100;
      break;

    }

    return $value;
}

echo randomType();

class RandomType {
  public function value(): mixed {

    $value;

    switch(rand(1, 5)) {

      case 1: $value = "Good day fellow!";
      break;
      case 2: $value = 10.22;
      break;
      case 3: $value = true;
      break;
      case 4: $value = ['Sport', 'Movies'];
      break;
      default: $value = 100;
      break;

    }

    return $value;

  }
}


echo (new Randomtype)->value();

callable

The callable return type in PHP allows a function to indicate that it returns a callable or a function reference that can be called later.

function getMultiplier(int $factor): callable {
    return function (int $number) use ($factor) {
        return $number * $factor;
    };
}

$multiplyByTwo = getMultiplier(2);
echo $multiplyByTwo(5); 


$multiplyByThree = getMultiplier(3);
echo $multiplyByThree(6);

class Multiplier {

    public function __construct(public int $factor) {}

    public function getMultiplier(): callable {
        return function (int $number) {
            return $number * $this->factor;
        };
    }
}

$multiplyByTwo = (new Multiplier(2))->getMultiplier();
echo $multiplyByTwo(5);

$multiplyByThree = (new Multiplier(3))->getMultiplier();
echo $multiplyByThree(6);

resource

The resource return type is used to indicate that a function or method returns a resource type. Resource type is a special data type that represents an external resource, such as a file, a database connection or a network socket.

function openFile(string $filename): resource {

  $file = fopen($filename, "r");

  if (!$file) {
    throw new Exception("Failed to open file: $filename");
  }

  return $file;

}

class FileHandler {

  public function openFile(string $filename): resource {

    $file = fopen($filename, "r");

    if (!$file) {

      throw new Exception("Failed to open file: $filename");

    }

    return $file;

  }

}

class

Classes can also be a return type. In this example, the Zoo class has a method called getAnimal() that returns an object of the Animal class. The return type of this method is specified as Animal using the :Animal syntax after the method signature. This means the return type will be a type of Animal class or any of its subclasses.

class Animal {
  public function __construct(public string $name, public int $age) {}
}

function getAnimal(): Animal {
    return new Animal("Leo", 5);
}

print_r(getAnimal());

class Animal {
  public function __construct(public string $name, public int $age) {}
}

class Zoo {
  public function getAnimal(): Animal {
    return new Animal("Leo", 5);
  }
}

print_r((new Zoo())->getAnimal());

object

The object return type is similar to the :class return type but the major difference is, it will return instances of any class and not a particular class.

class Address {
  public function __construct(public string $street, public string $city, public string $state) {}
}

class Person {
  public function __construct(public string $name, public Address $address) {}

  public function getAddress(): object {
    return $this->address;
  }
}

$address = new Address("123 Main St", "Anytown", "CA");
$person = new Person("John Doe", $address);
$addressObj = $person->getAddress();

Note that since the return type of getAddress() is specified as :object, the returned value can be an instance of any class, not just Address.

union

What if we can not tell the actual type a class should return or do we want to intentionally make the return type for any class dynamic?

PHP allows us to include additional return types using the union type, this allows us to include alternate types by separating them with a pipe |.

function price(): int | float {
  return 10;
}

function price(): int | float {
  return 10.4;
}

class Socks {
  public function price(): int | float {
    return 10;
  }
}

(new Socks)->price();

class Socks {
  public function price(): int | float {
    return 10.4;
  }
}

(new Socks)->price();

The optional type can have as many as possible types separated by a pipe, this feature should not be abused.

What If We Want a Null Value Returned

To return a null type, we need to add ? in front of the return type.

function hello(): ?string {
  return null;
}

hello();

In this case, the return type of the function can be either a string or null. No exception will be thrown.

class Optional {

  public function hello(): ?string {
    return null;
  }

  public function number(): ?int {
    return null;
  }

  public function price(): ?float {
    return null;
  }
}

echo (new Optional)->hello();
echo (new Optional)->number();
echo (new Optional)->price();

Conclusion

Return types are an important feature in PHP that allows developers to specify the type of value that a function should return. By declaring a return type, PHP can ensure that the value returned by a function is of the expected type, which can help prevent errors and improve code quality.

In PHP 7 and later versions, developers can use several different types of return types, including scalar types like int, float, and string, as well as compound types like array and callable. Additionally, PHP 8 introduced new return types, including union types and mixed types, which provide even more flexibility for developers.

Type declarations in PHP can be used not only for return types but also for parameter types and class properties. Type declarations can help prevent type errors, improve code readability, and make code easier to maintain.

Значения возвращаются при помощи необязательного оператора возврата.
Возвращаемые значения могут быть любого типа, в том числе это могут
быть массивы и объекты. Возврат приводит к завершению выполнения функции и передаче
управления обратно к той строке кода, в которой данная функция была
вызвана. Для получения более детальной информации ознакомьтесь с описанием
return.

Замечание:

Если конструкция return не указана, то функция вернет
значение NULL.

int(3)

Fatal error: Uncaught TypeError: Return value of sum() must be of the type integer, float returned in - on line 5 in -:5
Stack trace:
#0 -(9): sum(1, 2.5)
#1 {main}
  thrown in - on line 5

Вернуться к: Функции

В мире программирования и сценариев существует два способа писать код. Первый из них — это написать длинные и монолитные разделы сценария. Другой — разбить код на аккуратные, автономные блоки, которые можно использовать повторно, не изобретая один и тот же код снова и снова. Очевидно, что второй метод предпочтительнее первого, а фундаментальным строительным блоком этого подхода к написанию сценариев PHP является функция.

Функция — это именованный блок кода, который может быть вызван из любого другого участка кода для выполнения определенной задачи. Значения (аргументы) могут быть переданы в функцию, чтобы их можно было использовать в сценарии функции, а функция, в свою очередь, может возвращать результаты в то место сценария, из которого она была вызвана.

Функции в PHP существуют в двух формах:

• Встроенные функции : функции, которые предоставляются вместе с PHP, чтобы облегчить вам жизнь веб-разработчика, например, print_r(), var_dump, gettype() fopen() и др.
• Пользовательские функции : помимо встроенных функций, мы можем создавать наши собственные пакеты кода и использовать их везде, где это необходимо, просто их вызывая.

Создание пользовательской функции PHP

Первым шагом в создании функции PHP является указание имени, по которому вы будете ссылаться на функцию. В соответствии с соглашением об именах для функций PHP, они должны начинаться с буквы или подчеркивания и не должны содержать каких-либо пробелов или знаков препинания. Важно также предусмотреть, чтобы имя вашей функции не конфликтовало ни с одной из встроенных функций PHP.

Функции PHP создаются с использованием ключевого слова function, за которым следует имя и, наконец, набор круглых скобок (). Затем тело функции (сценарий, выполняющий работу функции), которое заключено в фигурные скобки {}.

В приведенном ниже примере мы создаем функцию с именем report. Открывающая фигурная скобка ({) указывает начало кода функции, а закрывающая фигурная скобка (}) указывает конец функции. Функция выводит строку "Это моя первая функция". Чтобы вызвать функцию, просто напишите ее имя и вставьте за ним скобки ():

<?php

function report() {

  echo "Это моя первая функция";

}


report(); // вызов функции

?>

Результат выполнения кода:

Это моя первая функция

Параметры функции PHP

Параметры (или аргументы, как их чаще называют) могут быть переданы в функцию. Аргументы указываются после имени функции в круглых скобках (). Вы можете добавить сколько угодно аргументов, просто разделив их запятыми. К именам параметров применяются те же правила, которые применяются к именам переменных в целом.

В следующем примере есть функция с двумя аргументами ($car, $color). Когда вызывается функция my_car(), мы также передаем значения аргументов (например, Mazda), и это значения используется внутри функции:

<?php

function my_car($car, $color) {  // Указано два аргумента: $car и $color

  echo "Марка машины: $car и она имеет $color цвет";

}


$color = 'белый';
 

// Вызываем функцию и передаем ей два аргумента

my_car('Mazda', $color);  // Аргументы - строковой литерал и переменная

?>

Результат выполнения кода:

Марка машины: Mazda и она имеет белый цвет

В следующем примере вызываем функцию с двумя аргументами ($fname и $year) передавая разные значения:

<?php

function firstName($fname, $year) {

  echo "$fname Иванова. Родилась в $year <br>";

}


firstName("Надя", "1975");

firstName("Галя", "1978");

firstName("Света", "1983");

?>

Результат выполнения кода:

Надя Иванова. Родилась в 1975
Галя Иванова. Родилась в 1978
Света Иванова. Родилась в 1983

Передача параметров в функцию по ссылке

По умолчанию параметры функции передаются по значению, поэтому, если значение аргумента внутри функции изменяется, оно не затрагивается вне функции. Если нужно позволить функции изменять значения параметров, последние должны быть переданы по ссылке.

Передача параметров по ссылке выполняется добавлением амперсанда (&) к имени параметра в определении функции, как показано в примере ниже:

<?php

function getMultiply(&$num){

  $num *= $num;

  return $num;

}


$mynum = 5;

echo $mynum; // Результат: 5

getMultiply($mynum);

echo $mynum; // Результат: 25

?>

Результат выполнения кода:

5
25

Значения по умолчанию для параметров функции

Функции могут определять значения аргументов по умолчанию. Чтобы установить значение по умолчанию просто вставьте имя параметра, затем знак равенства (=) и значение по умолчанию:

<?php

function getYear($str, $num=15){

  echo "$str возраст $num лет \n";

}


echo getYear("Катя", 14); // Катя возраст 14 лет


echo getYear("Вася"); // Вася возраст 15 лет

?>

Результат выполнения кода:

Катя возраст 14 лет
Вася возраст 15 лет

В приведенном выше примере параметр $num имеет значение по умолчанию 15. Во втором вызове функции мы не передаем какое-либо значение для этого параметра, поэтому принимается значение по умолчанию 15. А вот параметр $str не имеет значения по умолчанию, поэтому он обязателен при вызове функции.

function my_car($car = 'Mazda', $color) - ERROR

Возврат значения из функции PHP

Функции могут возвращать значения в ту часть PHP сценария, из которой они были вызваны. Для возврата значения используется ключевое слово return. Возвращаемое значение может быть любого типа, включая массивы и объекты.

Оператор return может распологаться в любом месте функции. Когда интерпретатор доходит к оператору return, функция возвращает значение (если указано) и завершает свое выполнение. Если оператор return не указан или не указано возвращаемое значение, то функция вернет значение NULL.

В следующем примере возвращаемое функцией значение присваивается переменной:

<?php

//функция вместе с тремя параметрами

function getSum($num1, $num2, $num3) {
 
  $product = $num1 + $num2 + $num3;


  return $product; //возврат переменной

} 
 

// сохраняем возвращенное значение

$retValue = getSum(2, 3, 5);
 
echo "Сумма: $retValue";
 
?>

Результат выполнения кода:

Сумма: 10

Функция не может возвращать несколько значений. Но мы можем получить несколько результатов, возвращая массив, как показано в следующем примере:

<?php

function divideNum($dividend, $divisor){

  $quotient = $dividend / $divisor;

  $array = array($dividend, $divisor, $quotient);

  return $array;

}


// Инициализация переменных значениями из массива

list($dividend, $divisor, $quotient) = divideNum(15, 3);

echo $dividend; // Результат: 15

echo $divisor; // Результат: 3

echo $quotient; // Результат: 5

?>

Результат выполнения кода:

15
3
5

Строгая типизация

Обратите внимание, что в приведенном выше примере мы не указывали PHP-интерпретатору, к какому типу данных принадлежит переменная.

PHP — это слабо типизированный язык и он автоматически связывает тип данных с переменной в зависимости от ее значения. Благодаря этой особенности, мы можем добавлять строки к целому числу, не вызывая ошибки.

В PHP 7 были добавлена возможность объявления типов данных. Теперь для отдельных файлов можно включать режим строгой типизации strict. В этом режиме в функцию можно передавать значения только тех типов, которые объявлены для аргументов. В противном случае будет выбрасываться исключение TypeError.

В следующем примере функция получает параметры как число, так и строку, не используя strict:

<?php

function getSum(int $a, int $b) {

  return $a + $b;

}

echo getSum(7, "7 days");

// поскольку strict НЕ включен, "7 дней" заменяется на int (7), и возвращается 14
?>

Результат выполнения кода:

14

Для влючения режима строгой типизации используется выражение declare в объявлении strict_types, которое прописывается в верхней строке файла PHP:

<?php declare(strict_types=1); // включение strict

function getSum(int $a, int $b) {

  return $a + $b;

}

echo getSum(7, "7 days");

// поскольку strict включен и "7 дней" не является целым числом, будет выдана ошибка

?>

Результат выполнения кода будет примерно такой:

PHP Fatal error: Uncaught TypeError: Argument 2 passed to addNumbers() must be of the type integer, string given, called in /home/bWN0Ml/prog.php on line 6 and defined in /home/bWN0Ml/prog.php:3 Stack trace: #0 /home/bWN0Ml/prog.php(6): addNumbers(7, ‘7 days’) #1 {main} thrown in /home/bWN0Ml/prog.php on line 3

В этом примере мы передаём функции в качестве аргументов как число, так и строку, но здесь мы добавили строгий ррежим strict и получили фатальную ошибку.

Объявления типа возвращаемого значения

PHP 7 поддерживает объявление типа возвращаемого значения функции (return). Как и в случае с объявлением типа для аргументов функции, включение режима строгой типизации при несоответствии типа возвращаемого значения функции вызовет ошибку.

Чтобы объявить режима строгой типизации для возвращаемого значения функции, добавьте двоеточие (:) и тип прямо перед открывающей фигурной скобкой { при объявлении функции.

<?php declare(strict_types=1); // включение strict

function getSum(float $a, float $b) : float {

  return $a + $b;

}

echo getSum(1.5, 2.3);
 // вернёт 3.8
?>

Результат выполнения кода:

3.8

Укажем тип возвращаемого значения, отличный от типов аргументов, и убедимся, что тип возвращаемого значения функции является правильным:

<?php declare(strict_types=1); // включение strict

function getSum(float $a, float $b) : int {

  return (int)($a + $b);

}

echo getSum(1.5, 2.3);
 // вернёт 3
?>

Результат выполнения кода:

3

PHP Экзаменатор

Довольно часто при вызове функции она не только выполняет указанный
фрагмент программного кода, но и возвращает некоторое значение, которое является результатом ее работы. Осуществляется операция возврата при помощи
необязательного оператора return, который немедленно прекращает выполнение
текущей функции и возвращает свой аргумент как значение данной функции. При этом оператор return может быть
расположен в любом месте функции и, когда до него доходит управление, функция возвращает значение и завершает свое выполнение, передавая управление
обратно к той строке кода, в которой данная функция была вызвана. Если оператор return не указан или не указано
возвращаемое им значение, то функция вернет значение NULL (см. пример №1).

<?php

//Создаем функцию, принимающую два аргумента
function m_sum($a_1,$a_2){  
	//Вычисляем сумму и присваиваем переменной
	$sum = $a_1+$a_2;   		 
	//Возвращаем сумму в качестве значения функции 
	return  $sum;       		 
	
	//Эта инструкция выполнена не будет, т.к.
	//находится после оператора return
	$sum=100;       			 	  
} 

//Выведет 15
echo m_sum(5,10); 			 	 

?>

Пример №1. Возврат значений функции

Так как оператор return является языковой конструкцией, а не функцией, то использовать круглые скобки не нужно,
иначе это может привести к нежелательным эффектам.

Также следует добавить, что оператор return может использоваться и в глобальной области видимости, т.е. вне функций.
В таком случае он прекращает выполнение всего текущего файла скрипта.

В PHP функции не могут возвращать несколько значений, но аналогичного результата можно добиться, возвращая
массив (см. пример №2).

<?php

//Используем список аргументов переменной длины
function m_sum(...$sum){ 	   
	//Задаем стартовое значение счетчика
	$i=0; 										 
	//Перебираем все значения массива аргументов
	foreach($sum as $value){   
		//Помещаем аргументы функции в массив
		$new_array[$i]=$value;   
		//Увеличиваем значение счетчика на единицу
		$i+=1;									 
	}
	//Возвращаем полученный массив
	return $new_array;       	 
}
 
//Выведет второй элемент массива, т.е. 10
echo m_sum(5,10,15,20)[1]; 	 

/* Таким образом, данная функция принимает аргументы, помещает их в массив и 
затем возвращает этот массив в качестве своего значения */

?>

Пример №2. Возврат значения функции в виде массива значений

В PHP 7.0.0 была добавлена возможность объявлять тип возвращаемого значения,
аналогично объявлению типов принимаемых функцией аргументов. Соответственно, особенности, касающиеся как режима слабой типизации, так и режима строгой
типизации, справедливы и для возвращаемых функцией значений. Это значит, что в случае несоответствия возвращаемого значения указанному типу в режиме
слабой типизации делается попытка привести значение к корректному типу, а при включенном режиме строгой типизации, сразу же выводится ошибка.

Указывается тип возвращаемого значения при объявлении функции после круглых скобок с параметрами и двоеточия перед открывающей скобкой тела функции
(см. пример №3).

<?php

//Задаем режим строгой типизации для скрипта
declare(strict_types=1);  

//Задали тип string возвращаемого значения
function my_sum(int $a,int $b): string{  
	$sum=$a+$b; 
	//Возвращаемое значение должно быть типа string
	return  $sum;       		  
}
 
//При вызове функции выведет ошибку
echo my_sum(5,2);   			 
								
/* Напомним, что исключение составляет передача значения целочисленного 
типа функции, которая ожидает получить значение типа float. */		  

?>

Пример №3. Объявление типа возвращаемого функцией значения