class_alias
Creates a second, fully interchangeable name for an existing class at runtime.
class_alias(string $class, string $alias, bool $autoload = true): bool- Added in PHP 5.3.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$class | string | The name of the existing class to alias. May be a class, interface or trait name. |
$alias | string | The new name to register. It must not already be taken by another class, interface, trait or alias. |
$autoloadoptional | bool= true | Whether to run the registered autoloaders if class is not already loaded. |
Return value
boolReturns true on success or false on failure.
Errors
Emits an E_WARNING and returns false when the original class cannot be found (or loaded) or when the alias name is already in use.
Changelog
- PHP 8.3.0class_alias() can now create an alias of an internal class. Before 8.3 it emitted a warning and returned false for anything that was not a user-defined class.
class_alias() registers a second name that points at the exact same class. It is not inheritance and not a subclass: there is one class, reachable through two names. Objects created through the alias report the original name from get_class(), and instanceof works with either name.
When to reach for it
The realistic use is backwards compatibility. When you move App\Mailer into App\Mail\Mailer, alias the old name to the new one so existing code, serialized data and config strings keep working while you migrate. Frameworks also use it to expose short root-namespace names for deeply namespaced classes.
Things that trip people up
- Both names must be given fully qualified, without a leading backslash.
class_alias()takes strings, so the currentnamespaceandusestatements are ignored. - The alias is created when the call executes. If nothing has run
class_alias()yet, the alias does not exist — that is why it is normally placed inside an autoloader or a bootstrap file. - Aliasing an interface or trait works, but you still alias only the name; you cannot alias a name that does not exist yet unless the autoloader can produce it.
An alias cannot be removed once registered, and re-aliasing the same name is a failure, not an overwrite.
Example
When to use it
- Keep an old class name working after moving a class into a new namespace
- Expose a short global alias for a deeply namespaced framework class in a bootstrap file
- Swap a real implementation for a test double by aliasing the name before it is first autoloaded
Frequently asked questions
What is the difference between class_alias and extending a class?
class_alias creates another name for the same class, while extending creates a new, separate class. With an alias there is one class in memory, private members are shared, and get_class() reports the original name; with inheritance you get a distinct class that can override behaviour.
Does get_class return the alias or the real class name?
It returns the real class name. The alias only exists as a lookup entry, so any code that compares class-name strings must compare against the original name.
Can I use class_alias with namespaces?
Yes, but you must pass fully qualified names as strings without a leading backslash, for example class_alias('App\\Mail\\Transport', 'App\\Transport'). The current namespace and use statements have no effect on string arguments.
More examples
Aliasing across namespaces
Both names resolve to one class, so the constant is readable through either. The last line prints false because ::class is resolved at compile time from the literal text you wrote — it never collapses an alias back to the original name.
<?php
namespace App\Mail;
class Transport {
public const NAME = 'smtp';
}
\class_alias('App\\Mail\\Transport', 'App\\Transport');
echo \App\Transport::NAME, "\n";
var_dump(\class_exists('App\\Transport'));
var_dump(\App\Transport::class === \App\Mail\Transport::class);Guarding against a failed alias
The second alias attempt fails because the name Summary is already taken, and the third fails because the source class does not exist. Both return false rather than throwing, so the return value is the only signal you get — Whatever was never registered.
<?php
class Report {}
class_alias('Report', 'Summary');
$ok = @class_alias('Report', 'Summary');
var_dump($ok);
$missing = @class_alias('NoSuchClass', 'Whatever', false);
var_dump($missing);
var_dump(class_exists('Whatever', false));
Discussion