decoct()

Purpose

decoct() converts an integer into its base-8 (octal) representation. Octal uses only the digits 0 to 7, and each digit stands for exactly three bits. That is why it is still common when working with Unix-style permission modes such as 755 or 644.

The function returns a string, not a number. This matters because the result is meant for display, logging or formatting, not for further arithmetic.

Signature

Parameters and defaults

• $num: the integer to convert. It is required and has no default value.

The value you pass is an ordinary decimal integer as PHP sees it. Note that PHP stores integers as binary values internally. A literal such as 0755 and a literal such as 493 are the same number, and decoct() produces "755" for both of them.

Return value and failure cases

The function returns a string containing the octal digits, with no prefix and no leading zeros (except for the value zero, which gives "0"). It does not return false and it does not emit warnings for ordinary integers.

The largest convertible number depends on the platform. On 64-bit builds the biggest integer, 9223372036854775807, becomes 777777777777777777777. On 32-bit platforms the usual limit is 4294967295, giving 37777777777.

Failures come from the argument type. In the default coercive mode, a numeric string such as "15" is converted to an integer. A non-numeric string raises a TypeError. With declare(strict_types=1), passing anything other than an int raises a TypeError. A float with a fractional part passed in coercive mode loses precision and triggers a deprecation notice, so cast or round it explicitly first.

Example 1: the basic conversion

<?php
echo decoct(15) . "\n";
echo decoct(264) . "\n";

17
410

Fifteen is 1 * 8 + 7, so the result is 17. For 264, the digits come from 4 * 64 + 1 * 8 + 0, which is why the output is 410.

Example 2: showing permission modes

Octal literals in PHP start with a leading zero. Converting them back to octal text gives the familiar permission notation.

<?php
$modes = [0644, 0755, 0600];
$labels = array_map('decoct', $modes);
echo json_encode($labels) . "\n";

["644","755","600"]

Passing the function name as a string to array_map() works because decoct() takes a single argument. Each element is returned as a string, so the JSON output contains quoted values.

Example 3: padding and masking

Because the result has no leading zeros, you often pad it yourself. You can also mask the value to keep only the permission bits.

<?php
function formatMode(int $mode): string
{
    return str_pad(decoct($mode & 0777), 4, "0", STR_PAD_LEFT);
}

echo formatMode(0755) . "\n";
echo formatMode(0100644) . "\n";
echo formatMode(0) . "\n";

0755
0644
0000

The mask 0777 removes file-type bits such as the 0100000 part of 0100644. str_pad() then restores a fixed four-character width, so zero becomes 0000.

Edge cases

• Zero: decoct(0) returns the one-character string "0".
• Negative integers: the conversion works on the underlying bit pattern as an unsigned value, not with a minus sign. On a 64-bit build decoct(-1) yields a long string of 22 digits beginning with 1. Do not expect "-1".
• Large values: results are bound by the platform integer size, so code that must behave the same everywhere should not depend on values above the 32-bit range.
• No prefix: the string never contains a leading 0 or 0o. Add it yourself if you need it.

Common mistakes

1. Treating the result as a number. decoct(8) is the string "10". Adding to it gives decimal arithmetic on the digits 10, which has nothing to do with octal math.
2. Passing octal text instead of an integer. decoct("755") converts the decimal number 755, which gives 1363. Use octdec("755") first when your input is already octal text.
3. Forgetting the leading zero in literals. decoct(755) is not the same as decoct(0755). The first is decimal 755, and the second is decimal 493.
4. Passing fractional floats. Convert deliberately with (int) or intdiv() instead of relying on implicit conversion.
5. Expecting padding. If a fixed width matters, use str_pad() or sprintf().

Related functions

• octdec() converts an octal string back into a decimal integer.
• decbin() converts a decimal integer to binary.
• dechex() converts a decimal integer to hexadecimal.
• base_convert() converts a number string between arbitrary bases from 2 to 36.
• sprintf() with the %o format produces octal output and supports padding directly, for example sprintf("%04o", 8).

Recap

decoct(int $num): string turns an integer into an octal digit string without any prefix. It is most useful for presenting permission modes and other values grouped in three-bit chunks. Remember that the result is text, that negative numbers are shown as unsigned bit patterns, and that the maximum size depends on the platform. Use octdec() for the reverse direction.