Nota
Esta tabela ainda não é exaustiva e será completada à medida que a API de
tipos do FrankenPHP se tornar mais completa.
Tipos primitivos, arrays, `mixed` e `callable` são suportados atualmente,
especificamente para métodos de classe.
Objetos ainda não podem ser usados como parâmetros de métodos ou tipos de
retorno.
Se você consultar o trecho de código da seção anterior, poderá ver que os
auxiliares são usados para converter o primeiro parâmetro e o valor de retorno.
O segundo e o terceiro parâmetros da nossa função `repeat_this()` não precisam
ser convertidos, pois a representação em memória dos tipos subjacentes é a mesma
para C e Go.
#### Trabalhando com arrays
O FrankenPHP oferece suporte nativo para arrays PHP por meio de
`frankenphp.AssociativeArray` ou conversão direta para um mapa ou slice.
`AssociativeArray` representa um
[hashmap](https://en.wikipedia.org/wiki/Hash_table) composto por um campo
`Map: map[string]any` e um campo opcional `Order: []string` (ao contrário dos
arrays associativos do PHP, os mapas em Go não são ordenados).
Se a ordem ou a associação não forem necessárias, também é possível converter
diretamente para um slice `[]any` ou um mapa não ordenado `map[string]any`.
**Criando e manipulando arrays em Go:**
```go
//export_php:function process_data_ordered(array $input): array
func process_data_ordered_map(arr *C.zval) unsafe.Pointer {
// Converte um array associativo PHP para Go, mantendo a ordem
associativeArray := frankenphp.GoAssociativeArray(unsafe.Pointer(arr))
// percorre as entradas em ordem
for _, key := range associativeArray.Order {
value, _ = associativeArray.Map[key]
// faz algo com a chave e o valor
}
// retorna um array ordenado
// se 'Order' não estiver vazio, apenas os pares chave-valor em 'Order'
// serão respeitados
return frankenphp.PHPAssociativeArray(AssociativeArray{
Map: map[string]any{
"chave1": "valor1",
"chave2": "valor2",
},
Order: []string{"chave1", "chave2"},
})
}
//export_php:function process_data_unordered(array $input): array
func process_data_unordered_map(arr *C.zval) unsafe.Pointer {
// Converte um array associativo PHP em um mapa Go sem manter a ordem
// Ignorar a ordem terá melhor desempenho
goMap := frankenphp.GoMap(unsafe.Pointer(arr))
// percorre as entradas sem nenhuma ordem específica
for key, value := range goMap {
// faz algo com a chave e o valor
}
// retorna um array não ordenado
return frankenphp.PHPMap(map[string]any{
"chave1": "valor1",
"chave2": "valor2",
})
}
//export_php:function process_data_packed(array $input): array
func process_data_packed(arr *C.zval) unsafe.Pointer {
// Converte um array compactado PHP para Go
goSlice := frankenphp.GoPackedArray(unsafe.Pointer(arr), false)
// percorre o slice em ordem
for index, value := range goSlice {
// faz algo com a chave e o valor
}
// retorna um array compactado
return frankenphp.PHPackedArray([]any{"valor1", "valor2", "value3"})
}
```
**Principais recursos da conversão de arrays:**
- **Pares chave-valor ordenados** - Opção para manter a ordem do array
associativo;
- **Otimizado para múltiplos casos** - Opção para ignorar a ordem para melhor
desempenho ou converter diretamente para um slice;
- **Detecção automática de listas** - Ao converter para PHP, detecta
automaticamente se o array deve ser uma lista compactada ou um hashmap;
- **Arrays aninhados** - Os arrays podem ser aninhados e converterão todos os
tipos suportados automaticamente (`int64`, `float64`, `string`, `bool`, `nil`,
`AssociativeArray`, `map[string]any`, `[]any`);
- **Objetos não são suportados** - Atualmente, apenas tipos escalares e arrays
podem ser usados como valores.
Fornecer um objeto resultará em um valor `null` no array PHP.
##### Métodos disponíveis: empacotado e associativo
- `frankenphp.PHPAssociativeArray(arr frankenphp.AssociativeArray) unsafe.Pointer`
\- Converte para um array PHP ordenado com pares chave-valor;
- `frankenphp.PHPMap(arr map[string]any) unsafe.Pointer` - Converte um mapa em
um array PHP não ordenado com pares chave-valor;
- `frankenphp.PHPPackedArray(slice []any) unsafe.Pointer` - Converte um slice
em um array PHP compactado apenas com valores indexados;
- `frankenphp.GoAssociativeArray(arr unsafe.Pointer, ordered bool) frankenphp.AssociativeArray`
\- Converte um array PHP em um `AssociativeArray` Go ordenado (mapa com ordem);
- `frankenphp.GoMap(arr unsafe.Pointer) map[string]any` - Converte um array PHP
em um mapa Go não ordenado;
- `frankenphp.GoPackedArray(arr unsafe.Pointer) []any` - Converte um array PHP
em um slice Go.
### Declarando uma classe PHP nativa
O gerador suporta a declaração de **classes opacas** como estruturas Go, que
podem ser usadas para criar objetos PHP.
Você pode usar o comentário de diretiva `//export_php:class` para definir uma
classe PHP.
Por exemplo:
```go
//export_php:class User
type UserStruct struct {
Name string
Age int
}
```
#### O que são classes opacas?
**Classes Opacas** são classes cuja estrutura interna (propriedades) é ocultada
do código PHP.
Isso significa:
- **Sem acesso direto às propriedades**: Você não pode ler ou escrever
propriedades diretamente do PHP (`$user->name` não funcionará);
- **Interface somente para métodos** - Todas as interações devem passar pelos
métodos que você definir;
- **Melhor encapsulamento** - A estrutura interna de dados é completamente
controlada pelo código Go;
- **Segurança de tipos** - Sem risco do código PHP corromper o estado interno
com tipos incorretos;
- **API mais limpa** - Força o design de uma interface pública adequada.
Essa abordagem fornece melhor encapsulamento e evita que o código PHP corrompa
acidentalmente o estado interno dos seus objetos Go.
Todas as interações com o objeto devem passar pelos métodos que você definir
explicitamente.
#### Adicionando métodos às classes
Como as propriedades não são diretamente acessíveis, você **deve definir
métodos** para interagir com suas classes opacas.
Use a diretiva `//export_php:method` para definir o comportamento:
```go
//export_php:class User
type UserStruct struct {
Name string
Age int
}
//export_php:method User::getName(): string
func (us *UserStruct) GetUserName() unsafe.Pointer {
return frankenphp.PHPString(us.Name, false)
}
//export_php:method User::setAge(int $age): void
func (us *UserStruct) SetUserAge(age int64) {
us.Age = int(age)
}
//export_php:method User::getAge(): int
func (us *UserStruct) GetUserAge() int64 {
return int64(us.Age)
}
//export_php:method User::setNamePrefix(string $prefix = "User"): void
func (us *UserStruct) SetNamePrefix(prefix *C.zend_string) {
us.Name = frankenphp.GoString(unsafe.Pointer(prefix)) + ": " + us.Name
}
```
#### Parâmetros anuláveis
O gerador suporta parâmetros anuláveis usando o prefixo `?` em assinaturas PHP.
Quando um parâmetro é anulável, ele se torna um ponteiro na sua função Go,
permitindo que você verifique se o valor era `null` no PHP:
```go
//export_php:method User::updateInfo(?string $name, ?int $age, ?bool $active): void
func (us *UserStruct) UpdateInfo(name *C.zend_string, age *int64, active *bool) {
// Verifica se o parâmetro name foi fornecido (não nulo)
if name != nil {
us.Name = frankenphp.GoString(unsafe.Pointer(name))
}
// Verifica se o parâmetro age foi fornecido (não nulo)
if age != nil {
us.Age = int(*age)
}
// Verifique se o parâmetro active foi fornecido (não nulo)
if active != nil {
us.Active = *active
}
}
```
**Pontos-chave sobre parâmetros anuláveis:**
- **Tipos primitivos anuláveis** (`?int`, `?float`, `?bool`) tornam-se ponteiros
(`*int64`, `*float64`, `*bool`) em Go;
- **Strings anuláveis** (`?string`) permanecem como `*C.zend_string`, mas podem
ser `*nil`;
- **Verifique `nil`** antes de dereferenciar valores de ponteiro;
- **`null` do PHP torna-se `nil` do Go** - quando o PHP passa `null`, sua função
em Go recebe um ponteiro `nil`.
Aviso
Atualmente, os métodos de classe têm as seguintes limitações.
**Objetos não são suportados** como tipos de parâmetros ou tipos de retorno.
**Arrays são totalmente suportados** tanto para parâmetros quanto para tipos
de retorno.
Tipos suportados: `string`, `int`, `float`, `bool`, `array` e `void` (para
tipo de retorno).
**Tipos de parâmetros anuláveis são totalmente suportados** para todos os
tipos escalares (`?string`, `?int`, `?float`, `?bool`).
Após gerar a extensão, você poderá usar a classe e seus métodos no PHP.
Observe que você **não pode acessar propriedades diretamente**:
```php
setAge(25);
echo $user->getName(); // Saída: (vazio, valor padrão)
echo $user->getAge(); // Saída: 25
$user->setNamePrefix("Funcionária");
// ✅ Isso também funciona - parâmetros anuláveis
$user->updateInfo("João", 30, true); // Todos os parâmetros fornecidos
$user->updateInfo("Joana", null, false); // Age é nulo
$user->updateInfo(null, 25, null); // Name e active são nulos
// ❌ Isso NÃO funcionará - acesso direto à propriedade
// echo $user->name; // Error: Cannot access private property
// $user->age = 30; // Error: Cannot access private property
```
Este design garante que seu código Go tenha controle total sobre como o estado
do objeto é acessado e modificado, proporcionando melhor encapsulamento e
segurança de tipos.
### Declarando constantes
O gerador suporta a exportação de constantes Go para PHP usando duas diretivas:
`//export_php:const` para constantes globais e `//export_php:classconst` para
constantes de classe.
Isso permite que você compartilhe valores de configuração, códigos de status e
outras constantes entre código Go e PHP.
#### Constantes globais
Use a diretiva `//export_php:const` para criar constantes PHP globais:
```go
//export_php:const
const MAX_CONNECTIONS = 100
//export_php:const
const API_VERSION = "1.2.3"
//export_php:const
const STATUS_OK = iota
//export_php:const
const STATUS_ERROR = iota
```
#### Constantes de classe
Use a diretiva `//export_php:classconst ClassName` para criar constantes que
pertencem a uma classe PHP específica:
```go
//export_php:classconst User
const STATUS_ACTIVE = 1
//export_php:classconst User
const STATUS_INACTIVE = 0
//export_php:classconst User
const ROLE_ADMIN = "admin"
//export_php:classconst Order
const STATE_PENDING = iota
//export_php:classconst Order
const STATE_PROCESSING = iota
//export_php:classconst Order
const STATE_COMPLETED = iota
```
Constantes de classe são acessíveis usando o escopo do nome da classe no PHP:
```php
getName(); // "João Ninguém"
echo My\Extension\STATUS_ACTIVE; // 1
```
#### Notas importantes
- Apenas **uma** diretiva de namespace é permitida por arquivo.
Se várias diretivas de namespace forem encontradas, o gerador retornará um
erro;
- O namespace se aplica a **todos** os símbolos exportados no arquivo: funções,
classes, métodos e constantes;
- Os nomes de namespace seguem as convenções de namespace do PHP, usando barras
invertidas (`\`) como separadores;
- Se nenhum namespace for declarado, os símbolos serão exportados para o
namespace global como de costume.
### Gerando a extensão
É aqui que a mágica acontece e sua extensão agora pode ser gerada.
Você pode executar o gerador com o seguinte comando:
```console
GEN_STUB_SCRIPT=php-src/build/gen_stub.php frankenphp extension-init my_extension.go
```