# Pierwsze kroki

## Instalacja

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

shikiphp wymaga PHP 8.2 lub nowszej wersji z `ext-json` i `ext-mbstring` — oba są włączone w niemal każdej kompilacji PHP. Nic więcej: bez Node, natywnego powiązania Oniguruma ani dodatkowych rozszerzeń.

## Pierwszy blok kodu

Statyczna fasada `Shikiphp` to najprostszy sposób na rozpoczęcie. Przekaż kod, identyfikator języka i identyfikator motywu:

```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` zwraca kompletny blok `<pre class="shiki …">` z własnym stylem. Kolory tekstu i tła są zapisane inline w `<pre>`, dlatego blok renderuje się poprawnie bez dodatkowego arkusza stylów.

## Dwa motywy (jasny i ciemny)

Zamiast pojedynczego `theme` przekaż mapę `themes`. shikiphp generuje zmienne CSS
(np. Shiki), dzięki czemu jeden wyrenderowany blok dopasowuje się do jasnego i ciemnego trybu:

```php
use Shikiphp\Shikiphp;

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

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

Domyślnie kolory motywu `light` są zapisane inline, a `dark` jest udostępniany przez zmienne `--shiki-dark`. Aktywuj ciemny motyw za pomocą niewielkiej ilości CSS — ten sam fragment dokumentuje Shiki:

```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;
}
```

Możesz wybrać motyw, którego kolory mają być domyślnie zapisane inline, za pomocą opcji
[`defaultColor`](https://shikiphp.inline0.dev/pl/docs/options#defaultcolor) lub ustawić `defaultColor: false`,
aby generować wyłącznie zmienne.

## Identyfikatory języków i aliasy

Języki wskazuje się za pomocą identyfikatora lub aliasu Shiki — `php`, `ts`, `js`,
`rust`, `python`, `html` i podobnych. Informacje o wyświetlaniu pełnej listy dołączonych elementów znajdziesz w sekcji [Języki](https://shikiphp.inline0.dev/pl/docs/languages), a identyfikatory motywów w sekcji [Motywy](https://shikiphp.inline0.dev/pl/docs/themes).

## Ponowne użycie mechanizmu podświetlania

Fasada leniwie tworzy i buforuje dołączony mechanizm podświetlania `Highlighter`, dlatego kolejne wywołania
`Shikiphp::codeToHtml` korzystają z tych samych pamięci podręcznych gramatyk i motywów. Jeśli potrzebujesz
bogatszego API (wyniku HAST, własnych gramatyk, siatek tokenów), pobierz instancję bezpośrednio:

```php
use Shikiphp\Shikiphp;

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

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

Pełny zakres funkcji opisuje sekcja [API](https://shikiphp.inline0.dev/pl/docs/api).