Quick Start
***********

.[perex]
Learn how to work with Texy in just a few minutes. This page guides you through installation, first use, and basic configuration.


Installation
============

Texy leverages modern PHP features and requires at least version 8.1.

The simplest installation method is via Composer:

```bash
composer require texy/texy
```

Composer will automatically download Texy and all its dependencies.


First Use
=========


Basic Text Processing
---------------------

Creating a Texy instance and processing text is extremely simple:

```php
require __DIR__ . '/vendor/autoload.php';

$texy = new Texy\Texy;

$text = 'This is **bold text** and this is //italic//.';
$html = $texy->process($text);

echo $html;
```

Output:
```html
<p>This is <strong>bold text</strong> and this is <em>italic</em>.</p>
```

The `process()` method processes the entire text including block elements (paragraphs, headings, lists, tables...).


Single-line Text
----------------

If you're processing only single-line text without block elements (such as database headings or short descriptions):

```php
$texy = new Texy\Texy;

$text = 'Link to "homepage":https://example.com';
$html = $texy->processLine($text);

echo $html;
```

Output:
```html
Link to <a href="https://example.com">homepage</a>
```

The `processLine()` method doesn't wrap the output in a `<p>` paragraph and processes only inline elements.


Basic Configuration
===================

Texy works out of the box, but you'll often want to adjust the basic settings.


Setting Image Paths
-------------------

If you're using relative paths to images, set the root directory:

```php
$texy = new Texy\Texy;

// Web path (prepended to relative URLs)
$texy->imageModule->root = '/images/';

// Physical disk path (for determining dimensions)
$texy->imageModule->fileRoot = __DIR__ . '/public/images/';
```

Now when you write `[* photo.jpg *]`, Texy will generate `<img src="/images/photo.jpg">` and automatically determine the image dimensions.


Setting Link Paths
------------------

Similarly, you can set the root directory for links:

```php
$texy->linkModule->root = '/articles/';
```


Enabling and Disabling Syntaxes
-------------------------------

Each part of the Texy syntax can be disabled or enabled using the `$allowed` array:

```php
$texy = new Texy\Texy;

// Disable images
$texy->allowed['image'] = false;

// Disable HTML tags in input
$texy->allowed['html/tag'] = false;

// Enable emoticons (disabled by default)
$texy->allowed['emoticon'] = true;
```

A complete list of syntax options can be found in [configuration | configuration#allowed].


Safe Mode for User Content
--------------------------

If you're processing content from users (comments, forum posts), use safe mode:

```php
$texy = new Texy\Texy;
Texy\Configurator::safeMode($texy);

$userInput = $_POST['comment'];
$html = $texy->process($userInput);
```

SafeMode:
- Allows only **safe HTML tags** (`<strong>`, `<em>`, `<a>`, ...)
- Disables **classes and IDs**
- Disables **inline styles**
- Disables **images**
- Adds `rel="nofollow"` to all links
- Filters **URL schemes** (only `http:`, `https:`, `ftp:`, `mailto:`)

More about security in the chapter [Configuration – Security |configuration#Security].


Complete Example
================

```php
require __DIR__ . '/vendor/autoload.php';

$texy = new Texy\Texy;

// Configuration
$texy->imageModule->root = '/images/';
$texy->linkModule->root = '/';
$texy->allowed['html/tag'] = false;

// Text to process
$text = '


Article Heading
===============

This is an **introductory paragraph** with a link to "homepage":https://example.com.

- First item
- Second item
- Third item

[* photo.jpg .(Photograph) *]
';

// Processing
$html = $texy->process($text);

// Output
echo $html;

// Additional information
echo "Page title: " . $texy->headingModule->title;
print_r($texy->summary['links']);
print_r($texy->summary['images']);
```

After processing, you have access to:
- `$texy->headingModule->title` – first heading (suitable for `<title>`)
- `$texy->summary['links']` – array of all used links
- `$texy->summary['images']` – array of all used images


Next Steps
==========

Now you know how to use Texy. Continue with:

- **[Configuration | configuration]** – detailed settings for all modules
- **[Syntax | syntax]** – learn the Texy markup
- **[Architecture | architecture]** – understand how Texy works internally