narek / sharp-php
SharpPHP: a C#-like language that compiles to modern PHP.
Requires
- php: ^8.4
- ext-ctype: *
- ext-mbstring: *
Requires (Dev)
- illuminate/console: ^12.0 || ^13.0
- illuminate/support: ^12.0 || ^13.0
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^12.0
Suggests
- ext-curl: Needed by HttpClient (System.Net.Http) to send HTTP requests
- laravel/framework: Write controllers, services and models in SharpPHP inside a Laravel app (registered automatically)
Provides
None
Conflicts
None
Replaces
None
README
SharpPHP is a C#-like language that compiles to modern PHP. You write .sphp files with C# syntax — classes, static void Main, properties, generics, LINQ, switch expressions, pattern matching — and the compiler turns them into clean, readable PHP 8.4 code.
using System; using System.Collections.Generic; using System.Linq; namespace App; public class Program { public static void Main(string[] args) { var people = new List<Person> { new("Ann", 31), new("Bob", 17) }; foreach (var adult in people.Where(p => p.Age >= 18)) { Console.WriteLine($"{adult.Name} is {adult.Age}"); } } } public record Person(string Name, int Age);
Features
- The C# you know: classes, records, structs, interfaces, enums, properties, generics with constraints and
variance, extension methods, lambdas and closures, LINQ, pattern matching,
switchexpressions, exceptions with filters,usingandIDisposable,yield return,async/await: see the Language guide - C#'s semantics, not PHP's: integer division, value equality of records, banker's rounding, checked casts,
IndexOutOfRangeExceptionandNullReferenceException: see Semantics that match C# - The C# compiler's errors at compile time: types, arguments, definite assignment, access rules, missing
returns, with C#'s messages; exceptions are reported with
.sphplines: see Errors - A .NET-style library:
Console,Math,string,StringBuilder,DateTime,TimeSpan,List,Dictionary,HashSet,Queue,Stack, LINQ,Task,HttpClient,JsonSerializer,GC: see Runtime library - Web apps in the style of ASP.NET Core minimal APIs:
app.MapGet("/users/{id:int}", ...), see Web apps - Async and await on PHP fibers, with HTTP requests running at the same time: see Async and await
- PHP both ways: SharpPHP calls PHP classes, functions and Composer packages; PHP calls SharpPHP classes; collections and PHP arrays are converted: see Mixing PHP and SharpPHP
- Laravel: controllers, services, models and jobs written in SharpPHP: see Laravel
- Editors: PhpStorm and VS Code get highlighting, completion, parameter info, errors while typing, hover and go to definition: see PhpStorm setup and VS Code setup
- Command line: cached builds,
sharp run,sharp serve,sharp checkfor CI: see Command line
Contents
Requirements · Installation · Quick start · Command line · Web apps · PhpStorm setup · VS Code setup · Configuration · Language guide · Extension methods · Runtime library · Async and await · Mixing PHP and SharpPHP · Laravel · Errors · Memory · Differences from C# · Development
Requirements
- PHP 8.4 or newer, tested on 8.4 and 8.5 (the generated code uses property hooks and asymmetric visibility)
ext-mbstringandext-ctype(enabled in almost every PHP build)ext-curl, only forHttpClient
Installation
In your project folder (an empty folder or one with only index.php is fine: Composer creates
composer.json and vendor/ itself):
composer require armdevstack/sharp-php
Upgrading
composer update armdevstack/sharp-php # bug-fix releases: 0.7.0 → 0.7.x composer require armdevstack/sharp-php:^0.7 # a newer minor version: 0.6.x → 0.7.x
While SharpPHP is 0.x, a plain composer update stays within the minor version you installed: the
constraint Composer writes for you, e.g. ^0.7.0, means >=0.7.0 <0.8.0, because ^ does not cross a 0.x
minor version. Require the newer version once, as above, and composer update follows it from then on.
composer show armdevstack/sharp-php prints the installed version; CHANGELOG.md lists
what changed. The build in var/sharp is redone automatically after an upgrade.
On Windows, stop the language server before upgrading. While an editor runs it, it keeps
vendor/bin/sharp open, Windows does not let Composer replace that file, and the upgrade stops half-way
(Failed to open stream: Permission denied). In PhpStorm: View → Tool Windows → Language Servers,
right-click SharpPHP → Stop; in VS Code: close the project's window. Upgrade, then open a .sphp
file and the server starts again. After a failed upgrade, stopping the server and running
composer install completes it.
Quick start
1. Write a program in src/Program.sphp (any number of .sphp files in any sub-directories of src/):
using System; namespace App; public class Program { public static void Main(string[] args) { Console.WriteLine("Hello from SharpPHP!"); } }
2. Run it from the command line:
vendor/bin/sharp run # build (if needed) and run Main vendor/bin/sharp run -- a b c # pass arguments to Main(string[] args)
or from PHP, e.g. index.php (PhpStorm runs it with the green ▶ button):
<?php require_once __DIR__ . '/vendor/autoload.php'; exit(SharpPhp\Project::fromDirectory(__DIR__)->run(array_slice($argv ?? [], 1)));
$ php index.php Hello from SharpPHP!
Builds are cached: sources are recompiled only when a .sphp file (or the compiler) changes.
3. Ignore the build output if the project uses git — add to .gitignore:
/vendor/ /var/
4. Set up your editor for highlighting, completion and errors while typing: see PhpStorm setup or VS Code setup (two minutes, once per editor).
Command line
| Command | Description |
|---|---|
sharp run [--project=DIR] [-- args] |
Build if needed and run the entry point |
sharp serve [--project=DIR] [--port=8000] [--host=localhost] |
Serve a web app with PHP's built-in web server |
sharp build [--project=DIR] [--force] |
Compile all sources to PHP |
sharp check [--project=DIR] |
Compile without writing files (CI) |
sharp compile <file.sphp> |
Print the PHP generated for one file |
sharp clean [--project=DIR] |
Delete the build directory |
sharp lsp |
The language server, for editors (LSP over stdin/stdout): see Other editors |
sharp vscode [--package=FILE] |
Install the VS Code extension, or only write its .vsix: see VS Code setup |
sharp --version |
Print the version |
In a Laravel app, php artisan sharp:build [--force] builds the sources (see Laravel).
Web apps
The same program can answer HTTP requests. System.Web is a small web framework in the style of
ASP.NET Core minimal APIs:
using System; using System.Collections.Generic; using System.Linq; using System.Net; using System.Web; namespace App; public class Program { public static void Main(string[] args) { var users = new List<User> { new(1, "Ann"), new(2, "Bob") }; var app = WebApp.Create(); app.MapGet("/", req => "Hello from SharpPHP!"); app.MapGet("/hello/{name}", req => Results.Html($"<h1>Hello, {WebUtility.HtmlEncode(req.Route["name"])}!</h1>")); app.MapGet("/users", req => users.Select(u => new { u.Id, u.Name })); app.MapGet("/users/{id:int}", req => { var user = users.FirstOrDefault(u => u.Id == int.Parse(req.Route["id"]!)); return user is null ? Results.NotFound() : Results.Json(user); }); app.MapPost("/users", req => { var name = req.Form["name"]; if (string.IsNullOrEmpty(name)) { return Results.BadRequest(new { Error = "name is required" }); } return Results.Created("/users/3", new { Id = 3, Name = name }); }); app.Run(); } } public record User(int Id, string Name);
Run it: vendor/bin/sharp serve (or php index.php, or sharp run: app.Run() started from the
command line starts the server, like dotnet run) and open http://localhost:8000. Sources are
recompiled on the next request after a change. Files in wwwroot/ (CSS, images, scripts) are served as
they are; nothing else of the project is reachable from the browser.
Routes: MapGet, MapPost, MapPut, MapPatch, MapDelete, Map (any method), MapFallback.
Patterns: /users/{id}, constraints {id:int} (int, long, bool, alpha, guid), optional
{year?}, catch-all {*path}. Literal segments match case-insensitively; the most specific route
wins (/users/me beats /users/{id}); a path with no route for the method gets 405 with Allow.
The request (HttpRequest req): Method, Path, QueryString, Url, Body, ContentType, and the
read-only collections Query, Form, Route, Headers, Cookies. Their keys are case-insensitive and a
missing key reads as null: req.Query["page"] ?? "1". GetValues("tag") returns every value of a
repeated key, TryGetValue("q", out var q) and ContainsKey(...) work as on a dictionary.
The response: what the handler returns.
| Handler returns | Response |
|---|---|
a string |
200, text/plain |
Results.Html(html), Results.Text(...), Results.Content(text, type) |
that content |
Results.Json(value) or any other value (objects, anonymous objects, lists, dictionaries) |
JSON with camelCase names |
Results.Ok(), Created(uri, value), NoContent(), BadRequest(), Unauthorized(), Forbid(), NotFound(), Conflict(), StatusCode(n), Redirect(url) |
that status (with the value as JSON when one is given) |
| nothing | an empty 200 |
Responses are immutable; add headers and cookies with .WithHeader(name, value),
.WithCookie(name, value, maxAgeSeconds: 3600) and .WithStatusCode(n). A class of your own can
implement IResult (HttpResponse ToResponse()).
Testing: app.Handle(new HttpRequest("GET", "/users/2")) returns the HttpResponse
(StatusCode, Body, Headers, ContentType) without a server.
In production point the web server at the project and send every request that is not a file in
wwwroot/ to index.php (PHP-FPM, Apache or nginx), e.g. for nginx:
root /var/www/app/wwwroot; location / { try_files $uri /index.php$is_args$args; } location = /index.php { fastcgi_pass unix:/run/php/php-fpm.sock; include fastcgi_params; fastcgi_param SCRIPT_FILENAME /var/www/app/index.php; }
Errors: an unhandled exception or a compile error answers 500 with a page that shows the error and
the .sphp line while PHP's display_errors is on (development), and a generic page when it is off
(production). The details always go to the server log. Console.WriteLine in a handler writes to the
server's terminal or log, not to the page, as in ASP.NET Core; a console program (no WebApp) opened in
a browser shows its output as plain text.
PhpStorm setup
PhpStorm (and every other JetBrains IDE) gets highlighting, completion, parameter info, errors while typing,
hover and go to definition for .sphp files. Setting it up takes about two minutes and is done once per IDE: it
then works in every project that requires armdevstack/sharp-php (parameter info needs 0.6 or newer:
composer show armdevstack/sharp-php prints the version, Upgrading tells how to update).
1. Syntax highlighting
- Settings → Editor → TextMate Bundles, click +.
- Choose the folder
vendor/armdevstack/sharp-php/editors/sharpphpof your project and click OK.
Keywords, types, strings, numbers and comments in .sphp files are now colored.
2. Completion, parameter info, errors while typing, hover, go to definition
These come from the SharpPHP language server (vendor/bin/sharp lsp) through the free
LSP4IJ plugin by Red Hat:
- Settings → Plugins → Marketplace: search LSP4IJ, click Install (restart PhpStorm if it asks).
- Settings → Languages & Frameworks → Language Servers (LSP4IJ), click +.
- In the New Language Server dialog, open the Template list, choose Import template... and
select the folder
vendor/armdevstack/sharp-php/editors/lsp4ij/sharpphp. Click OK.
Check it: open a .sphp file, type Console. inside Main: WriteLine, Write, ReadLine are listed.
View → Tool Windows → Language Servers shows the SharpPHP server running.
What you get:
| Feature | Example |
|---|---|
| Members after a dot, also in unfinished code | user. → Name, Age, Greet(); Person. → static members; names. → Add, Count, Where, ... |
| Names in scope | local variables, parameters, members of the class, types, keywords |
| Namespaces | using System. → Collections, Linq, Web, ... |
| Parameter info | new Random( → Random(int? seed = ...), title.PadLeft(5, → string string.PadLeft(int totalWidth, string paddingChar = ...) with the argument being typed in bold; shown at ( and ,, and with ⌘P / Ctrl+P |
| Errors while typing | the same errors as sharp build, underlined where they are |
| Hover | (property) string Person.Name, (method) string Person.Greet(string greeting) |
| Go to definition | ⌘-click / Ctrl-click a name: its declaration, also in another file |
3. Running programs
- Console programs: right-click
index.php→ Run 'index.php' (or the green ▶). PhpStorm needs a PHP interpreter for this: Settings → PHP → CLI Interpreter. In the terminal:vendor/bin/sharp run. - Web apps (Web apps): run
vendor/bin/sharp servein the terminal (orindex.phpas above) and open http://localhost:8000. - Errors (compile errors and exceptions) name the
.sphpfile and line.
4. Optional: the generated PHP
The compiled PHP goes to var/sharp. If your PHP code uses classes written in SharpPHP, keep the folder
indexed: PhpStorm then completes those classes in .php files too. Otherwise right-click var/sharp →
Mark Directory as → Excluded, so that searches show only your sources.
Troubleshooting
| Problem | What to do |
|---|---|
.sphp files are plain text |
Remove *.sphp under Settings → Editor → File Types → Text, if it is there; check step 1 |
| No completion and no error marks | Check that LSP4IJ is installed (Settings → Plugins → Installed) and step 2 was done. The project must require SharpPHP: composer require armdevstack/sharp-php. Restarting PhpStorm alone does not turn completion on |
| The Language Servers window shows that SharpPHP cannot start | PhpStorm did not find php (common on macOS, where an IDE started from the Dock does not see Homebrew). In Settings → Languages & Frameworks → Language Servers (LSP4IJ) → SharpPHP, set Command: to the full path of PHP: /opt/homebrew/bin/php $PROJECT_DIR$/vendor/bin/sharp lsp (which php in a terminal prints the path) |
| You want to see what the server does | View → Tool Windows → Language Servers → SharpPHP: the Logs tab; for every request set Trace: to verbose on the server's Debug tab |
| No completion after a dot | The file has a syntax error somewhere else: fix it first (it is underlined) |
composer update fails on Windows with vendor\bin/sharp): Failed to open stream: Permission denied |
The running language server keeps that file open: stop it (Language Servers → right-click SharpPHP → Stop), run composer install, then open a .sphp file again (see Upgrading) |
VS Code setup
VS Code gets the same features through the SharpPHP extension, which ships with the package: highlighting, completion, parameter info, errors while typing (also in the Problems panel), hover and go to definition (F12). It is installed once and works in every project that requires SharpPHP.
- In a terminal, in the project folder:
vendor/bin/sharp vscode. It installs the extension with VS Code'scodecommand (without it:vendor/bin/sharp vscode --package=sharpphp.vsix, then Extensions → ⋯ → Install from VSIX...). - Reload VS Code: Command Palette (⇧⌘P / Ctrl+Shift+P) → Developer: Reload Window.
- Open the project folder (the one with
vendor/) and trust it when VS Code asks: in Restricted Mode only highlighting works, because the language server runs the project's PHP.
Check it: open a .sphp file, type Console. inside Main: WriteLine, Write, ReadLine are listed.
View → Output → SharpPHP shows Language server running.
| Problem | What to do |
|---|---|
| "PHP was not found" | Set Settings → Extensions → SharpPHP → Php: Path (sharpphp.php.path) to the full path of PHP 8.4+, e.g. /opt/homebrew/bin/php (which php prints it) |
| No completion and no error marks | View → Output → SharpPHP says why: no vendor/bin/sharp (composer require armdevstack/sharp-php) or an untrusted workspace |
| Anything else | Command Palette → SharpPHP: Restart Language Server; details in editors/sharpphp |
After upgrading SharpPHP, run vendor/bin/sharp vscode again to update the extension.
Other editors
Any editor with an LSP client (Neovim, Sublime Text, Zed, Helix, ...) can run php vendor/bin/sharp lsp
for *.sphp files, language id sharpphp. The TextMate grammar for highlighting is
editors/sharpphp/syntaxes/sharpphp.tmLanguage.json.
Configuration
Optional, in the project's composer.json:
"extra": { "sharp": { "source": "src", "output": "var/sharp" } }
The output directory contains the generated PHP (classes/) and manifest.php (class map, entry point, source map). Add it to .gitignore.
Language guide
Program structure
namespace App;(file-scoped) ornamespace App { ... }using System;,using MyApp.Models;, aliasesusing Col = System.Collections.Generic;System,System.Collections.Generic,System.Linq,System.Threading.TasksandSystem.Net.Httpare imported implicitly (as in .NET)- Entry point: a
static void Main()/static int Main(string[] args)method, or top-level statements (the returnedintbecomes the exit code)
Types
class,abstract,sealed,static class,interface,enum,record,struct(compiled as a final class, so it has reference semantics)- Single inheritance plus interfaces:
class Book : Product, IComparable<Book> - Constructors with
: base(...), expression-bodied constructors, static constructors - Fields,
const,readonly,static - Properties: auto (
{ get; set; },{ get; private set; },{ get; init; }, get-only), with initializers, expression-bodied (=> ...), fullget { } set { }withvalue, abstract and interface properties, static properties (with accessor bodies they becomeget_Name()/set_Name()methods) - Methods:
virtual/override/abstract(an override may return a more derived type), expression bodies, default and named arguments,params,ref,out(incl.out var xand the discardout _),in - Extension methods: a static method of a non-generic
static classwhose first parameter is declaredthisis called like a method of that parameter's type, see Extension methods - Finalizers
~Name() { ... }, which run when the object is freed (see Memory) - Records:
record Point(int X, int Y);with value equality (==), C#-styleToString()(every public property) andwithexpressions (p with { X = 5 }) - Enums:
enum Color { Red, Green = 5 },(int)color,(Color)1,color.ToString() - Nullable value types:
int?,Color?,DateTime?withHasValue,Value(InvalidOperationExceptionwhen there is none) andGetValueOrDefault();default(T), new arrays andFirstOrDefault()give C#'s defaults (0,false, an enum's member of value 0,DateTime.MinValue,nullforint?)
Generics
- Generic classes, interfaces and methods:
class Box<T>,interface IRepository<T>,T Max<T>(T a, T b) - Constraints:
where T : IShape, new()— a class/interface constraint becomes the PHP parameter type - Variance as in C#:
List<Dog>is not aList<Animal>(classes are invariant), whileIEnumerable<Dog>,Dog[]andFunc<Dog>are anIEnumerable<Animal>, anAnimal[]and aFunc<Animal>, and anAction<Animal>is anAction<Dog>. Interfaces declare it:interface IProducer<out T>,interface IConsumer<in T>; the compiler checks thatout Tis only produced andin Tonly consumed (SP1961) - Type inference for generic methods, including through lambdas:
box.Map(x => x * 2)is aBox<int> - The compiler tracks generic arguments, so
List<string>elements are known to be strings (names[0].Length) - Runtime checks:
new List<int>()rejects non-integers, like C# (ArgumentException) - Implementing a generic interface with a concrete type (
IRepository<User>) is supported
Extension methods
namespace App.Extensions; public static class StringExtensions { public static string Shout(this string text) => text.ToUpper() + "!"; } public static class SequenceExtensions { public static T Second<T>(this IEnumerable<T> items) => items.Skip(1).First(); }
using App.Extensions; "hi".Shout(); // "HI!": compiled to StringExtensions::Shout('hi') new List<string> { "a", "b" }.Second(); // "b", a string: T comes from the receiver
- Found as in C#: in the file's namespace, the namespaces around it, and the imported ones (
using App.Extensions;) - A method of the receiver's own type wins over an extension method of the same name. Among extension methods the most specific
thistype wins (this stringbeforethis object); two equally specific ones make the call ambiguous (SP0121) - Strings, numbers, arrays, collections, classes, interfaces and type parameters can be extended. A
nullreceiver is passed to the method (which can check it);text?.Shout()skips the call - The static form works too:
StringExtensions.Shout("hi"), and PHP code callsStringExtensions::Shout('hi') - Only in a non-generic
static class, as astaticmethod, withthison the first parameter (SP1106, SP1105, SP1100) - Completion after a dot lists the extension methods that apply; parameter info and hover show them as C# does
Statements and expressions
if/else,while,do,for,foreach(incl.foreach (var (key, value) in dict)),break,continueswitchstatements (with patterns andwhen),switchexpressionstry/catch/finally, exception filters (catch (E e) when (...)),throw;, throw expressions (x ?? throw ...)using (var file = Open()) { ... },using (expression) ...andusing var file = Open();(disposed at the end of the block):Dispose()runs however the block is left, in reverse order for several resourcesyield return/yield breakwithIEnumerable<T>- Lambdas
x => x * 2,(a, b) => { ... }, closures with C# capture semantics, method groups (list.ForEach(Print)) - Pattern matching:
is T x,is null,is not null,is > 0 and < 10,or,not,var,_, property patterns (Circle { R: > 10 } c,{ Name: var n, Age: >= 18 },{ Home.City: "Paris" }) - String interpolation with format specifiers
$"{price:F2}", verbatim strings@"C:\path",$@"..." ?.,?[],??,??=,is,as, casts,typeof/GetType()(aSystem.TypewithName,FullName,Namespace),nameof,default- Object and collection initializers:
new User { Name = "Ann" },new Dictionary<string, int> { ["a"] = 1 },new(),[1, 2, 3] - Anonymous types:
new { Id = 1, user.Name }, with read-only typed properties, value equality and C#'sToString()({ Id = 1, Name = Ann })
Semantics that match C#
| C# | Generated PHP |
|---|---|
7 / 2 (ints) |
\intdiv(7, 2) → 3 |
"a" + 1 |
'a' . 1 |
a == b |
$a === $b (records compare by value) |
true.ToString() |
"True" |
(int)obj |
checked unboxing (InvalidCastException) |
(Laptop)product |
checked cast |
catch (Exception e) |
catches every PHP \Throwable |
arr[10], arr[10] = x (out of range) |
IndexOutOfRangeException (PHP would add the element) |
Math.Round(2.5) |
2 (banker's rounding) |
(int)'A', 'a' + 1, c - '0' |
65, 97 + 1, \mb_ord($c) - 48 (char is an integral type) |
(char)66, c++ |
\mb_chr(66), $c = \mb_chr(\mb_ord($c) + 1) |
obj.Name when obj is null |
NullReferenceException |
end - start, date + span (DateTime, TimeSpan) |
DateTime::op_Subtraction($end, $start) (a TimeSpan), DateTime::op_Addition($date, $span) |
a < b, a == b (dates, spans) |
DateTime::Compare($a, $b) < 0, DateTime::Compare($a, $b) == 0 (by value) |
n.HasValue, n.Value (int? n) |
$n !== null, $n ?? throw new InvalidOperationException(...) |
Runtime library
System maps to SharpPhp\Runtime\System, and works as in .NET. System, System.Collections.Generic,
System.Linq, System.Threading.Tasks and System.Net.Http are imported implicitly; the other namespaces
below need a using.
| Type | Members |
|---|---|
Console |
WriteLine, Write, ReadLine; composite formatting: Console.WriteLine("{0} costs {1:F2}", name, price) |
Math |
Abs, Atan2, Cbrt, Ceiling, Clamp, Cos, Exp, Floor, Log, Log10, Log2, Max, Min, Pow, Round (banker's rounding), Sign, Sin, Sqrt, Tan, Truncate; PI, E, Tau |
string / String |
Length, s[i]; Compare, CompareTo, Concat, Contains, EndsWith, Equals, Format, IndexOf, Insert, IsNullOrEmpty, IsNullOrWhiteSpace, Join, LastIndexOf, PadLeft, PadRight, Remove, Replace, Split, StartsWith, Substring, ToCharArray, ToLower, ToLowerInvariant, ToUpper, ToUpperInvariant, Trim, TrimEnd, TrimStart; string.Empty. Equals, Compare, Contains, StartsWith, EndsWith, IndexOf, LastIndexOf and Replace take a StringComparison (OrdinalIgnoreCase, ...): the IgnoreCase kinds ignore case, and as SharpPHP has no cultures the culture kinds compare as Ordinal |
StringBuilder (System.Text) |
Append, AppendLine, AppendFormat, AppendJoin, Insert, Remove, Replace, Clear, ToString, Length (settable), Capacity, sb[i]; the changing methods return the builder, so calls chain |
char |
IsDigit, IsLetter, IsLetterOrDigit, IsLower, IsUpper, IsWhiteSpace, ToLower, ToUpper; a char is a number in arithmetic (c - '0') |
int, long, short, byte, sbyte, ushort, uint, ulong |
Parse, TryParse (OverflowException out of range), MaxValue, MinValue, CompareTo, ToString("D3") |
double, float, decimal |
Parse, TryParse, IsNaN, IsInfinity, NaN, PositiveInfinity, NegativeInfinity, Epsilon, MaxValue, MinValue, ToString("F2") |
bool |
Parse, TryParse; ToString() gives True / False |
DateTime |
Now, UtcNow, Today, MinValue, MaxValue, UnixEpoch; new DateTime(2024, 12, 31[, 18, 30, 0[, 500]][, DateTimeKind.Utc]), new DateTime(ticks); Year, Month, Day, Hour, Minute, Second, Millisecond, Microsecond, DayOfWeek, DayOfYear, Date, TimeOfDay, Ticks, Kind; Add, AddYears, AddMonths (Jan 31 + 1 month is the end of February), AddDays, AddHours, AddMinutes, AddSeconds, AddMilliseconds, AddTicks, Subtract, ToUniversalTime, ToLocalTime, SpecifyKind, Compare, CompareTo, Equals, DaysInMonth, IsLeapYear; ToString() with the standard formats (d, D, f, F, g, G, M, o, R, s, t, T, u, U, Y) and custom ones (yyyy-MM-dd HH:mm:ss.fff, ddd, dddd, MMM, MMMM, h, tt, zzz, K, 'literal'), also $"{date:yyyy-MM-dd}"; ToShortDateString, ToLongDateString, ToShortTimeString, ToLongTimeString; Parse, TryParse, ParseExact; date - date (a TimeSpan), date + span, date - span, +=, -=, <, >, <=, >=, ==, !=; JSON as ISO 8601 ("2024-01-15T09:30:00"); DateTimeKind, DayOfWeek |
TimeSpan |
new TimeSpan(h, m, s), (d, h, m, s[, ms]), (ticks); FromDays, FromHours, FromMinutes, FromSeconds, FromMilliseconds, FromTicks, Zero, MaxValue, MinValue; Days, Hours, Minutes, Seconds, Milliseconds, Microseconds, Ticks, TotalDays, TotalHours, TotalMinutes, TotalSeconds, TotalMilliseconds; Add, Subtract, Negate, Duration, Multiply, Divide, Compare, CompareTo, Equals; ToString() (c, g, G, custom hh\:mm\:ss, d\.hh\:mm), Parse, TryParse; +, -, -span, comparisons; OverflowException beyond its range |
Convert |
ToBoolean, ToDouble, ToInt32, ToString |
Environment |
NewLine, Exit, GetEnvironmentVariable |
Random |
Next, NextDouble |
Array |
Empty, Exists, Fill, Find, IndexOf, Resize, Reverse, Sort; arrays have Length and the LINQ methods |
Type (typeof(T), value.GetType()) |
Name, FullName, Namespace |
List<T> |
Count, list[i], Add, AddRange, Clear, Contains, Exists, Find, FindAll, FindIndex, ForEach, GetRange, IndexOf, Insert, Remove, RemoveAll, RemoveAt, Reverse, Sort, ToArray, TrueForAll |
Dictionary<TKey, TValue> |
Count, Keys, Values, dict[key] (KeyNotFoundException when missing), Add, Clear, ContainsKey, ContainsValue, GetValueOrDefault, Remove, TryAdd, TryGetValue; foreach (var (key, value) in dict), KeyValuePair |
HashSet<T> |
Count, Add, Clear, Contains, ExceptWith, IntersectWith, Remove, UnionWith |
Queue<T> / Stack<T> |
Count, Enqueue, Dequeue, TryDequeue, Peek, Clear / Count, Push, Pop, Peek, Clear |
| LINQ, on arrays and collections | Aggregate, All, Any, Average, Concat, Contains, Count, Distinct, ElementAt, First, FirstOrDefault, GroupBy, Last, LastOrDefault, Max, Min, OrderBy, OrderByDescending (then ThenBy, ThenByDescending), Reverse, Select, SelectMany, SequenceEqual, Single, Skip, SkipWhile, Sum, Take, TakeWhile, ToArray, ToDictionary, ToList, Where, Zip (with a result selector); Enumerable.Range, Enumerable.Repeat |
Task, Task<T> |
Run, Delay, WhenAll, WhenAny, FromResult, FromException, CompletedTask; Result, Wait, IsCompleted, IsCompletedSuccessfully, IsFaulted, Exception: see Async and await |
HttpClient (needs ext-curl) |
GetStringAsync, GetAsync, PostAsync, PutAsync, DeleteAsync, AddDefaultHeader, BaseAddress, Timeout, Dispose; HttpResponseMessage (StatusCode, IsSuccessStatusCode, ReasonPhrase, Headers, Content.ReadAsStringAsync(), EnsureSuccessStatusCode()), StringContent |
WebUtility (System.Net) |
HtmlEncode, HtmlDecode, UrlEncode, UrlDecode |
JsonSerializer (System.Text.Json) |
Serialize(value, options) with JsonSerializerOptions (WriteIndented, PropertyNamingPolicy = JsonNamingPolicy.CamelCase) |
System.Web |
WebApp, HttpRequest, HttpResponse, Results, IResult: see Web apps |
| Memory | GC (Collect, CollectionCount, GetTotalMemory, KeepAlive, ReRegisterForFinalize, SuppressFinalize, WaitForPendingFinalizers), WeakReference<T>, WeakReference, ConditionalWeakTable<TKey, TValue> (System.Runtime.CompilerServices), new object(): see Memory |
| Interfaces | IDisposable (for using), IComparable<T> (for OrderBy and Sort), IEquatable<T>, IEnumerable<T> |
| Exceptions | Exception (Message, InnerException, StackTrace), SystemException, ArgumentException, ArgumentNullException, ArgumentOutOfRangeException, ArithmeticException, DivideByZeroException, FormatException, IndexOutOfRangeException, InvalidCastException, InvalidOperationException, KeyNotFoundException, NotImplementedException, NotSupportedException, NullReferenceException, OverflowException, TimeoutException, HttpRequestException; classes of your own can derive from them |
Async and await
async methods and lambdas, await, Task and Task<T> work as in C#, and HttpClient sends requests in
the background, so a program can wait for many things at once:
using System; using System.Linq; public class Program { public static async Task Main() { var http = new HttpClient(); var urls = new[] { "https://example.com", "https://example.org", "https://example.net" }; // The three downloads run at the same time: this takes as long as the slowest one. string[] pages = await Task.WhenAll(urls.Select(u => http.GetStringAsync(u))); Console.WriteLine(pages.Sum(p => p.Length)); int seconds = await CountdownAsync(3); Console.WriteLine($"{seconds} seconds later"); } static async Task<int> CountdownAsync(int seconds) { for (var i = seconds; i > 0; i--) { Console.WriteLine(i); await Task.Delay(1000); } return seconds; } }
- Methods:
async Task/async Task<T>(andasync void); inside,return value;returns theT.static async Task Main()(orTask<int>) andawaitin top-level statements work: the program ends when its task does. An async method runs right away until its firstawait, as in C#. - Lambdas:
async () => await LoadAsync(),async x => { ...; return x; }forFunc<Task>,Func<int, Task<string>>, ... - Task:
Task.Run(() => ...),Task.Delay(ms),Task.WhenAll(tasks)(aT[]of the results, in order; also for a collection of tasks),Task.WhenAny(tasks),Task.FromResult(x),Task.CompletedTask; on a task:.Resultand.Wait()(blocking),IsCompleted,IsFaulted,Exception. An exception thrown in a task comes out of theawait. - HttpClient (
System.Net.Http, needs PHP's curl extension):GetStringAsync,GetAsync,PostAsync,PutAsync,DeleteAsyncwithnew StringContent(text, null, "application/json");BaseAddress,Timeout(seconds),AddDefaultHeader(name, value). The response hasStatusCode,IsSuccessStatusCode,ReasonPhrase,Headers,Content.ReadAsStringAsync()andEnsureSuccessStatusCode(); failures throwHttpRequestException.
How it works: each async method runs in a PHP Fiber on SharpPHP's event loop; await suspends the fiber
until the task completes. It is one thread, like JavaScript: timers and network requests overlap, CPU work
does not, and PHP calls that block (sleep(), file_get_contents() of a URL, PDO queries) block everything
while they run. Use Task.Delay and HttpClient to wait without blocking.
Mixing PHP and SharpPHP
A project can be partly PHP and partly SharpPHP: write typed business logic in .sphp files and keep
frameworks, libraries and existing code in PHP. Each side calls the other.
SharpPHP calling PHP
- Any PHP class is visible: global classes directly (
new ArrayObject()), namespaced ones throughusing:using GuzzleHttp;thennew Client(). PHP's types (and PHPStan-style docblocks such as@return array<string, int>) are known to the compiler. - Where a .NET type of the runtime library has the name of a global PHP class (
DateTime,Exception), the .NET type wins, asSystemis imported. Name the PHP class through an alias:using PhpDateTime = DateTime;, thennew PhpDateTime("now").format("Y-m-d"). - Global PHP functions and constants can be called directly:
strlen(s),in_array(x, list),PHP_EOL.
PHP calling SharpPHP
Compiled classes are regular PHP classes. Make them loadable with one line:
require 'vendor/autoload.php'; SharpPhp\Project::fromDirectory(__DIR__)->autoload(); // builds if needed echo App\Pricing::Total([new App\Item('Book', 12.5, 2)], 'AM');
Collections and PHP arrays are converted where the two sides meet:
| Where | What happens |
|---|---|
A List, Dictionary, HashSet passed to PHP code that takes an array |
it becomes a PHP array (a dictionary becomes key => value): implode(", ", names), Store.save(names) |
A PHP array assigned to (or passed as) a List<T>, Dictionary<K, V>, HashSet<T> |
it becomes that collection, with C#'s element type checks: Dictionary<string, int> stock = Store.stock(); |
PHP code passing an array to a SharpPHP method with a List<T> / Dictionary<K, V> / HashSet<T> parameter |
the method converts it on entry: Pricing::Total([$item1, $item2]) |
json_encode() (and Laravel's JSON responses) of a SharpPHP collection |
a JSON array, or a JSON object for a dictionary |
A PHP array kept as it is (var stock = Store.stock();) can be indexed (stock["apple"]), iterated over
its values and queried with LINQ. PHP turns the array key "7" into the integer 7; collections of
strings and dictionaries with string keys turn such keys back into strings.
Laravel
In a Laravel app (11 or newer), controllers, services, models and jobs can be written in SharpPHP next
to the PHP ones. composer require armdevstack/sharp-php registers the integration automatically
(package discovery): .sphp files under app/ are compiled, and Laravel's routes, container and PHP code
use their classes like any other.
// app/Http/Controllers/UserController.sphp using System.Collections.Generic; using System.Linq; using Illuminate.Support.Facades; using HttpRequest = Illuminate.Http.Request; namespace App.Http.Controllers; public record User(int Id, string Name); public class UserController : Controller { private readonly List<User> users = new() { new(1, "Ann"), new(2, "Bob") }; public string Show(string name) => $"Hello, {name}!"; public List<User> Index(HttpRequest request) { Log.info("users listed"); return users.Take(int.Parse(request.query("limit", "10"))).ToList(); // sent as JSON } }
// routes/web.php (PHP, as usual) use App\Http\Controllers\UserController; Route::get('/hello/{name}', [UserController::class, 'Show']); Route::get('/users', [UserController::class, 'Index']);
- Namespaces follow the folders, as in PHP:
app/Http/Controllersisnamespace App.Http.Controllers;. A SharpPHP class can extend a PHP class (Controller,Model,Job), and PHP classes can use SharpPHP ones. - Dependency injection and route parameters work as for PHP controllers: Laravel passes
Request, services and{name}by parameter type and name. - Facades and helpers:
using Illuminate.Support.Facades;thenLog.info(...),Config.get(...),Route.has(...),DB.table(...); helper functions as they are:view("welcome"),url("/"),response(). The compiler knows the facades' methods from their docblocks (@method static ...), so arguments and results are checked, and the language server completes them. Calls it knows nothing about (Eloquent'sUser.where(...), other__callStatic/__callmagic) are passed through to PHP. - Name clashes:
Requestis bothIlluminate.Http.Requestand theRequestfacade; with both namespaces imported the compiler reports the ambiguity, as C# does. Use an alias (using HttpRequest = Illuminate.Http.Request;) or the full name. - Responses: return a string, a view, a Laravel response, or SharpPHP values: a
List, aDictionary, a record or an anonymous object becomes a JSON response. - Development: sources are recompiled on the next request after a change. Compile errors show on
Laravel's error page with the
.sphpfile and line; Artisan keeps working andphp artisan sharp:buildlists them. - Production: run
php artisan sharp:buildwhen deploying. WithAPP_ENV=productionthe app uses that build without checking the sources on every request. - Configuration:
.sphpfiles underapp/, compiled tostorage/framework/sharp(kept out of git by its own.gitignore). Change it in the app'scomposer.json:"extra": { "sharp": { "source": "app", "output": "storage/framework/sharp" } }.
Errors
Compile errors are reported in MSBuild style with a code frame:
src/Program.sphp(12,27): error SP0103: The name 'x' does not exist in the current context
12 | Console.WriteLine(x);
| ^
Like the C# compiler, SharpPHP rejects at compile time (not at runtime):
- values that do not convert to the target type:
int a = "text";,if (count),Sq("abc"),return "x";from anintmethod,list.Add("s")on aList<int> - wrong argument counts and unknown named arguments, for methods, constructors,
base(...)and delegates (calling a .NET overload the runtime library does not implement is reported as such) - methods, getters and lambdas where not all code paths return a value;
switchsections that fall through - reading a local variable before it is definitely assigned (
break,continue,return,try/finallyand constant conditions such aswhile (true)are taken into account);outparameters not assigned before returning private/protectedmembers and constructors used from outside, assignments to get-only, init-only andreadonlymembers, setters that are not accessible- classes that do not implement their interfaces (with matching parameter counts) or inherited abstract members
The checks never reject valid C#, so where SharpPHP cannot be sure it accepts the code:
- a conversion is only rejected when both types are known: values of type
object,dynamicor unconstrained type parameters, and untyped PHP code, are checked at runtime - all integer types are one type to the compiler, so narrowing (
int i = someLong;) and nullable-to-value (int i = maybeNull;) assignments are not reported - assignments inside
&&,||and?:count as definite assignments
Uncaught exceptions are printed like .NET, with locations mapped back to the .sphp sources:
Unhandled exception. System.InvalidOperationException: Queue empty.
at App.Worker.Next() in /app/src/Worker.sphp:line 14
at App.Program.Main() in /app/src/Program.sphp:line 8
Memory
SharpPHP uses PHP's memory management, which frees objects earlier and more predictably than .NET's garbage collector:
- An object is freed as soon as its last reference goes (reference counting); objects that only reference
each other are freed by PHP's cycle collector, which runs by itself and on
GC.Collect(). - So a finalizer (
~Name(), compiled to__destruct) runs right then, not on some later collection, andGC.WaitForPendingFinalizers()has nothing to wait for.GC.SuppressFinalize(this)inDispose()stops it, as in .NET. The base class's finalizer runs after the derived one. - For resources (files, connections, locks) use
IDisposablewithusing: it releases them at a known point, also when an exception is thrown. - In a web request all memory is freed when the request ends, so leaks matter only in long-running processes
(console daemons, async servers).
GC.GetTotalMemory(false)ismemory_get_usage(). - PHP's
memory_limitcaps a process; going over it is a fatal error, not a catchableOutOfMemoryException. WeakReference<T>andConditionalWeakTabledon't keep their targets alive (PHP'sWeakReferenceandWeakMap).
Differences from C#
SharpPHP is a C# subset on top of PHP's runtime. Notable differences:
- No method or constructor overloading (PHP has one method per name; names are case-insensitive)
- Generics are checked by the compiler and erased at runtime (only the built-in collections check element types);
typeof(List<int>).NameisList, andnew T()is not supported objectstands for any value, also as a generic argument:IEnumerable<object> xs = new List<int>()compiles (C# rejects it,intbeing a value type)- Finalizers run when the object is freed, at a known point (see Memory), not when a garbage collection happens to run
- Arrays (
int[]) are PHP arrays and are copied on assignment and when passed to a method (value semantics); a lambda that writes an element of a captured array changes it, as in C# - Integer arithmetic is 64-bit and does not wrap:
int.MaxValue + 1is2147483648, not-2147483648 ulongis limited tolong.MaxValue(there is noulong.MaxValue);decimal/float/doubleare PHP floatscharis a one-character string at runtime (it converts to its code where C# would use it as a number)- Values only know their PHP type at runtime:
5L.GetType()isSystem.Int32, whiletypeof(long)isSystem.Int64 - The runtime library implements the common .NET APIs, not all of them (no
DateTimeOffset,TimeZoneInfo,DateOnly,TimeOnly,Zipwithout a result selector, which returns tuples, ...) - There are no cultures:
DateTimeandTimeSpanformat and parse as .NET's invariant culture does (1/15/2024 9:30:00 AM, English names), and local time is PHP's default time zone (date_default_timezone_get()).DateTime.Parsereads what PHP's date parser reads (ISO 8601,1/15/2024 4:30 PM,January 15, 2024), except relative dates such astomorrow - A field of a struct type without an initializer (
public DateTime Due;) is null until it is set; C# starts it atDateTime.MinValue.default, new arrays andGetValueOrDefault()give C#'s defaults - A named argument for a
paramsparameter (string.Join(separator: ",", values: words)) is not supported; pass it positionally async/awaitruns on one thread (Fibers and an event loop): waiting overlaps, CPU work does not; there is noCancellationToken,ConfigureAwait,ValueTaskorIAsyncEnumerable- Not supported: nested types, operator overloading in your own types (
DateTimeandTimeSpanhave their operators), indexers, events/delegates declarations, LINQ query syntax, tuples,goto,reflocals andrefreturns, local functions, positional patterns (Point(0, 0)), passing arguments to a base record, implementingIEnumerable<T>in a class (derive fromList<T>instead), explicit interface implementations,dynamicarguments forparamsparameters
Development
composer install composer test # PHPStan (max level) + PHPUnit: lexer, diagnostics, code generation, runtime, end-to-end fixtures composer analyse # PHPStan only
End-to-end tests live in tests/Fixtures/<name>/: src/*.sphp plus the expected output.
Architecture
src/
Lexer/ source text -> tokens
Parser/ tokens -> syntax tree (src/Syntax)
Semantics/ types, symbols (project + PHP reflection), name resolution, and the language
rules: Conversions, AccessRules, ArgumentMatcher
Compiler/ Declarator (project-wide symbols), ImplementationVerifier, Compiler (pipeline), diagnostics
CodeGen/ Emitter: syntax tree -> PHP, with type inference and source maps; FlowState
(reachability and definite assignment)
Runtime/ the System library and helpers used by generated code
Project.php cached builds and running
Cli/ the `sharp` command