# Aloitus

## Asennus

```bash
composer require shikiphp/shikiphp
```

shikiphp vaatii version PHP 8.2 tai uudemman sekä `ext-json`n ja `ext-mbstring`n — nämä ovat käytössä lähes kaikissa PHP-koontiversioissa. Muita vaatimuksia ei ole: ei Nodea, natiivia Oniguruma-sidosta eikä lisälaajennuksia.

## Ensimmäinen lohkosi

Staattinen `Shikiphp`-julkisivu on nopein tapa aloittaa. Anna koodisi, kielen tunnus ja teeman tunnus:

```php
use Shikiphp\Shikiphp;

$html = Shikiphp::codeToHtml(<<<'PHP'
<?php
function greet(string $name): string {
    return "Hello, {$name}!";
}
PHP, [
    'lang'  => 'php',
    'theme' => 'github-dark',
]);

echo $html;
```

`codeToHtml` palauttaa kokonaisen, valmiiksi tyylitellyn `<pre class="shiki …">`-lohkon. Etualan ja taustan värit kirjoitetaan suoraan kohteeseen `<pre>`, joten lohko näkyy oikein ilman erillistä tyylitiedostoa.

## Kaksi teemaa (vaalea ja tumma)

Yhden `theme`n sijaan anna `themes`-kartta. shikiphp tuottaa CSS-muuttujia (kuten Shiki), joiden ansiosta sama renderöity lohko mukautuu vaaleaan ja tummaan tilaan:

```php
use Shikiphp\Shikiphp;

$code = 'const answer: number = 42';

echo Shikiphp::codeToHtml($code, [
    'lang'   => 'ts',
    'themes' => ['light' => 'github-light', 'dark' => 'github-dark'],
]);
```

Oletuksena `light`-teeman värit ovat rivinsisäisiä oletusarvoja, ja `dark` tuodaan saataville muuttujina `--shiki-dark`. Ota tumma teema käyttöön pienellä määrällä CSS-koodia — sama esimerkki, jonka Shiki dokumentoi:

```css
html.dark .shiki,
html.dark .shiki span {
  color: var(--shiki-dark) !important;
  background-color: var(--shiki-dark-bg) !important;
  /* and font styles */
  font-style: var(--shiki-dark-font-style) !important;
  font-weight: var(--shiki-dark-font-weight) !important;
  text-decoration: var(--shiki-dark-text-decoration) !important;
}
```

Voit valita rivinsisäiseksi oletukseksi käytettävän teeman valinnalla [`defaultColor`](https://shikiphp.inline0.dev/fi/docs/options#defaultcolor) tai määrittää arvon `defaultColor: false`, jolloin tulosteeseen tulee vain muuttujia.

## Kielen tunnukset ja aliakset

Kieliin viitataan niiden Shiki-tunnuksella tai aliaksella — `php`, `ts`, `js`, `rust`, `python`, `html` ja niin edelleen. Katso kohdasta [Kielet](https://shikiphp.inline0.dev/fi/docs/languages), miten kaikki mukana toimitetut kielet luetellaan, ja kohdasta [Teemat](https://shikiphp.inline0.dev/fi/docs/themes) teemojen tunnukset.

## Korostimen uudelleenkäyttö

Julkisivu luo laiskasti mukana toimitetun `Highlighter`n ja tallentaa sen välimuistiin, joten toistuvat `Shikiphp::codeToHtml`-kutsut käyttävät uudelleen samoja kielioppi- ja teemavälimuisteja. Jos tarvitset monipuolisemman APIn (HAST-tulosteen, mukautettuja kielioppeja tai tokenruudukoita), hae instanssi suoraan:

```php
use Shikiphp\Shikiphp;

$code = 'fn main() {}';

$highlighter = Shikiphp::highlighter();
$hast = $highlighter->codeToHast($code, ['lang' => 'rust', 'theme' => 'nord']);
```

Katso kaikki käytettävissä olevat ominaisuudet kohdasta [API](https://shikiphp.inline0.dev/fi/docs/api).