---
layout: ../../layouts/DocsLayout.astro
title: Welcome
pagesLayout:
- path: index
- path: install
- path: cheatsheet
- path: basics
  title: Basics
  children:
  - path: hello-world
  - path: comments
  - path: variables
  - path: datatypes
  - path: operators
- path: flow-control
  title: Flow control
  children:
  - path: conditionals
  - path: loops
  - path: match
  - path: blocks
- path: data-structures
  title: Data structures
  children:
  - path: tuples
  - path: arrays
  - path: maps
  - path: enums
  - path: unions
- path: functions
  title: Functions
  children:
  - path: declaration
  - path: parameters
  - path: higher-order
  - path: lambdas
- path: error-handling
  title: Error handling
  children:
  - path: "null"
  - path: try
- path: classes
  title: Classes
  children:
  - path: definition
  - path: static
  - path: interfaces
  - path: anonymous
  - path: magic
- path: templating
  title: Templating
  children:
  - path: intro
---
import InteractiveCode from "../../components/InteractiveCode.astro";
import Code from "../../components/Code.astro"


# Welcome

Welcome to the documentation of the THP programming languague.

THP is a new programming language that compiles to PHP.

![Accurate visual description of THP](/img/desc_thp.jpg)


This page details the main design desitions of the language,
if you want to install THP go to the [installation guide](install)


## Interactive execution

The documentation contains snippets of interactive THP code, like this:

<InteractiveCode 
    code={`
    val x = "android"
    var y = 17

    fun f(Int a, Int b) {
        print("hello, {a} {b}")
    }

    f(x, y)
    `}
    steps={`
    step {line 1}
    step {
        line 2
        set "String x" "\\"android\\""
    }
    step {
        line 8
        set "Int y" "17"
    }
    step {line 4}
    step {line 5}
    step {
        out "hello, android 17"
        line 6
    }
    step {line 8}
    step {line 0}
    `}
></InteractiveCode>

Use the `Step` and `Reset` buttons to emulate the execution of a
THP program!

## Goals

- Bring static typing to PHP: Generics, type checks at compile and runtime.
- Reduce implicit type conversion to a minimum.
- Remove the inconsistencies in the language.
- Organize the PHP stdlib.
- Have clear distinctions between Arrays, Tuples, Maps and Sets.
- Implement Union types
- Create a **consistent** language.
- Have typings for popular libraries (like TS's `.d.ts`).
- Have a simple instalation and configuration (requiring just Composer).
- Ship a fast, native binary (written in Rust) (why use PHP when we can go **_blazingly fast_**?).
- Support in-place compilation.
- Implement an LSP server.
- Implement a formatter.


## Not goals

These are **not** aspects that THP looks to solve or implement.

- Be what TypeScript is for JavaScript (PHP with types).
- Strictly adhere to PHP syntax/conventions.

THP **_intentionally_** uses a different syntax from PHP to signal
that it is a different language, and has different semantics.


## Some differences with PHP

```php
// PHP
$has_key = str_contains($haystack, 'needle');
print("has key? " . $has_key);
```

<Code thpcode={`
// THP
val has_key = haystack.contains("needle")
print("has key? " + has_key)
`} />

- Explicit variable declaration
- No `$` for variable names (and thus no `$$variable`, use a map instead)
- No semicolons
- Use methods on common datatypes
- Strings use only double quotes
- String concatenation with `+`


<br/>
<br/>

```php
// PHP
$obj = [
    'names' => ['Toni', 'Stark'],
    'age' => 33,
    'numbers' => [32, 64, 128]
]
```

<Code thpcode={`
// THP
val obj = .{
    names: #("Toni", "Stark"), // Tuple
    age: 33,
    numbers: [32, 64, 128]
}
`} />

- Tuples, Arrays, Sets, Maps are clearly different
- JSON-like object syntax

<br/>
<br/>

```php
// PHP
$cat = new Cat("Michifu", 7);
$cat->meow();
```


<Code thpcode={`
// THP
val cat = Cat("Michifu", 7)
cat.meow()
`} />

- Instantiate classes without `new`
- Use dot `.` instead of arrow `->` syntax

<br/>
<br/>

```php
// PHP
use \Some\Deeply\Nested\Class
use \Some\Deeply\Nested\Interface
```


<Code thpcode={`
// THP
use Some::Deeply::Nested::{Class, Interface}
`} />

- Different module syntax
- Explicit module declaration
- PSR-4 required
- No `include`, `include_once`, `require` or `require_once`

<br/>
<br/>


Other things:

- Pattern matching
- ADTs


## Runtime changes

Where possible THP will compile to available PHP functions/classes/methods/etc.

For example:

<Code thpcode={`
// This expression
val greeting = 
    match get_person()
    case Some(person) if person.age > 18
    { 
        "Welcome, {person.name}"
    }
    case Some(person)
    {
        "I'm sorry {person.name}, you need to be 18 or older"
    }
    case None
    {
        "Nobody is here"
    }
`} />

```php
// Would compile to:
$greeting = null;
$_person = get_person();
if ($_person !== null) {
    if ($_person["age"] > 18) {
        $greeting = "Welcome, " . $_person["name"];
    }
    else {
        $greeting = "I'm sorry " . $_person["name"] . ", you need to be 18 or older";
    }
}
else {
    $greeting = "Nobody is here";
}
```

However, more advanced datatypes & helper functions will require a sort of
runtime (new classes/functions/etc) or abuse the language's syntax/semantics.


