O que é o PrizeX
O PrizeX é uma plataforma de prêmios, jogos e marketplace feita em PHP: leilões, loteria, caixas misteriosas, um conjunto de jogos de arcade, uma loja de e-commerce multivendedor e uma economia de carteira/moedas — tudo em uma única aplicação auto-hospedada. Vem com uma arquitetura de plugins e temas, um painel administrativo e 38 plugins de gateway de pagamento cobrindo cartões, carteiras, cripto e processadores regionais, além de 3 métodos de pagamento manuais semeados pelo kernel.
Não existe amarra de SaaS: você instala na sua própria hospedagem, é dono do banco de dados e recebe atualizações vitalícias na licença. Cada vertical (leilões, loteria, caixas misteriosas, jogos, loja) pode ser ligada ou desligada de forma independente pelo painel administrativo — uma instalação nova pode rodar como um produto de uma vertical só ou como a suíte completa.
O código principal nunca tem dependência rígida de um plugin. Toda vertical, gateway de pagamento e login social é um plugin dentro de plugins/ que pode ser ativado, desativado ou excluído sem quebrar o resto do site.
Prefixo de tabela tbl_, sem ORM, quase tudo com prepared statements. Cada plugin é dono das próprias tabelas e faz a migração delas por um instalador idempotente com db_delta().
Onde ele roda
O PrizeX roda em hospedagem compartilhada comum ou em VPS — sem configuração especial de servidor além de um servidor web capaz de reescrever URLs.
* Vários arquivos em database/migrations/ usam a extensão ADD COLUMN IF NOT EXISTS, exclusiva do MariaDB. O MySQL 8.0/8.4 puro a rejeita — use MariaDB no banco de dados, tanto em desenvolvimento quanto em produção.
Como colocar uma instalação nova no ar
Não existe assistente de instalação para uma configuração nova — você importa o schema direto e configura o arquivo de ambiente.
- Instale as dependências do PHP:
composer install - Copie o modelo de ambiente e preencha as credenciais do seu banco de dados:
cp .env.example .env - Importe o
database/production.sqlno banco de dados indicado no seu.env— isso cria o schema completo. - Substitua a conta de administrador semeada (veja o aviso abaixo) e faça login em
/admin/.
database/production.sql traz uma linha em tbl_admin (admin@wowcodes.in) cujo hash de senha é idêntico em toda instalação. Exclua essa linha e insira a sua antes de ir ao ar:
php -r "echo password_hash('your-password', PASSWORD_BCRYPT), \"\n\";"DELETE FROM tbl_admin;
INSERT INTO tbl_admin (username, email, password, image, status, permission_settings)
VALUES ('yourname', 'you@example.com', '<hash from the command above>', '', 1, 1);Para desenvolvimento local, o servidor embutido do PHP funciona sem Apache: php -S localhost:8000 router.php — repare que esse servidor ignora o .htaccess por completo, então o router.php reimplementa as mesmas regras de roteamento na mão (veja Configuração do servidor web).
Variáveis de ambiente
Todas as configurações específicas de ambiente ficam no .env, carregado via vlucas/phpdotenv. Copie o .env.example para .env (ignorado pelo git) e defina valores reais para cada ambiente — as credenciais do banco de dados, no mínimo, antes de importar o schema.
As configurações gerais do site que não dependem do ambiente (nome do app, moeda, plugins ativos, tema ativo e os interruptores de cada vertical) ficam no banco de dados, na tbl_settings, e são gerenciadas pelo painel administrativo, não em arquivos.
Configuração do servidor web
As regras de roteamento e segurança — URLs amigáveis, bloqueio de acesso direto a .env/connection.php/logs e a proteção que impede o conteúdo enviado de rodar como PHP — são definidas em arquivos .htaccess espalhados pelo projeto. Apache e LiteSpeed/OpenLiteSpeed leem esses arquivos nativamente.
No nginx, use o nginx.conf.example, que espelha cada uma dessas regras em um bloco server{} do nginx — ajuste o server_name, o root e o socket do PHP-FPM para o seu ambiente.
.htaccess (produção), o router.php (servidor de desenvolvimento local php -S) e o nginx.conf.example (nginx) reimplementam as mesmas regras de roteamento de forma independente. Adicionar uma nova rota com URL amigável significa atualizar os três.
Arquitetura de requisições
Toda página da loja (index.php, item.php, …) inicializa passando pelo includes/header.php, nesta ordem:
O connection.php inicia a sessão, conecta via mysqli usando as credenciais do .env, carrega a tbl_settings em constantes como APP_NAME e CURRENCY e faz o login do usuário atual mais uma linha de impressão digital do dispositivo. O plugins_load() inicializa todos os plugins ativos e dispara o hook plugins_loaded — é nesse ponto que o conjunto real e atual de verticais ativas passa a ser conhecido, e é por isso que o header.php revalida depois as flags antigas de configuração (loja, multivendedor, leilão, loteria) contra o estado real de plugin ativo.
O painel administrativo não duplica essa inicialização — o admin/includes/connection.php define a configuração de sessão e de erros específica do admin e depois inclui o mesmo includes/connection.php da raiz.
Sistema de plugins
Um plugin é plugins/<slug>/plugin.php — metadados em comentário de cabeçalho, lidos sem executar o arquivo — mais um plugin.json opcional com informações mais ricas de catálogo. Os plugins ativos ficam guardados como um array JSON em tbl_settings.active_plugins.
- Propriedade das tabelas — cada plugin define o próprio
includes/schema.php, chamado na ativação, usando o helper idempotentedb_delta()(CREATE TABLE IF NOT EXISTS+ALTER TABLE ADD COLUMNapenas aditivo). Um plugin nunca mexe nas tabelas de outro plugin. - Os registros carregam primeiro —
add_admin_page,add_route,add_cron_job,add_api_routeeregister_modulesão todos definidos antes de qualquer plugin carregar, então as chamadas de topo de um plugin nunca dão erro fatal, mesmo que ele acabe inativo. - Remoção limpa — excluir um plugin executa o
uninstall.phpdele e apaga a pasta; nada fora deplugins/<slug>/deve depender obrigatoriamente dos arquivos dele, então o resto do site continua funcionando sem o plugin.
Sistema de temas
Um tema fica em assets/themes/<slug>/ — um manifest.php, um theme.css, um functions.php para os hooks do tema e uma pasta components/ opcional. O tema ativo fica guardado em tbl_settings.active_theme, com editorial como fallback caso nenhum esteja definido.
A resolução de componentes verifica, nesta ordem: a pasta components/ do próprio tema ativo, depois o diretório de componentes declarado por um plugin em register_module() e, por fim, a pasta components/ compartilhada na raiz. Na prática, isso significa que o padrão compartilhado existe uma única vez em components/, e qualquer tema — ou plugin de vertical ativo — pode sobrescrever um caminho de componente específico com a própria cópia.
Banco de dados
Prefixo de tabela tbl_, mysqli puro, quase tudo com prepared statements. Os arquivos SQL, em ordem de autoridade:
database/core-schema.sql— apenas as tabelas do kernel, mantidas à mão; as tabelas de verticais e de plugins ficam de fora de propósito.database/production.sql— gerado (schema principal + a rotina de instalação de cada plugin, exportada de um banco de dados descartável). É esse que você importa numa instalação nova.database/sandbox.sql— conjunto de dados de demonstração para desenvolvimento local.database/migration.sql— script de atualização consolidado e idempotente para instalações existentes.database/migrations/<slug>/up.sql(+down.sqlquando reversível) — um arquivo por migração individual.
Módulos
Todo módulo vem na mesma instalação e é ligado ou desligado de forma independente pelo painel administrativo.
Leilões
Lances ao vivo com portal de vendedores multivendedor e motor de comissões. Plugin principal: plugins/auction.
Loteria
Sorteios por bilhete com agendamentos, prêmios e notificações de ganhadores configuráveis. Plugin principal: plugins/lottery.
Caixa misteriosa
Pools de prêmios configuráveis com animações de revelação — o usuário compra uma caixa e vê na hora o que ganhou. Plugin: plugins/mystery-box.
Jogos e recompensas
Um conjunto de jogos de arcade em games/ mais plugins de engajamento e de ganhos:
Loja e marketplace
Uma camada de e-commerce multivendedor com promoções e ferramentas de merchandising. Plugins principais: plugins/shop, plugins/multivendor.
Carteira, moedas e investimentos
Uma carteira única para toda a plataforma, compartilhada por todos os módulos.
Indicações e recompensas
Autenticação, confiança e compliance
Utilitários
Painel administrativo
O painel administrativo fica em admin/ e não duplica a inicialização da loja — ele define a configuração de sessão e de erros específica do admin e depois inclui o mesmo includes/connection.php da raiz. As páginas se registram por add_admin_page(), que cuida da entrada na barra lateral, do controle de permissões, do CSRF e da moldura de autenticação; as ações JSON exclusivas do admin se registram por add_admin_ajax() e são despachadas via admin/ajax.php?action=<slug>.
Itens, banners, páginas, menus, blog.
Gestão de gateways automáticos e manuais, revisão de pagamentos manuais, exportação de repasses.
Grupos de usuários, papéis, dados do vendedor, login como usuário.
Exportação de transações, pedidos e usuários, logs de cron, rastreio de erros, logs de atividade do administrador.
Campanhas de e-mail, modelos, newsletters, notificações push, log de notificações.
Ativar e desativar plugins e temas, configurações de SEO por página, configurações gerais do site.
Temas da loja
Cinco temas vêm em assets/themes/, trocáveis por instalação pelo painel administrativo. Cada tema mantém a própria cópia dos componentes compartilhados na sua pasta components/.
Um visual simples e moderno, com cards brancos e sombras suaves — uma escolha segura e versátil para praticamente qualquer tipo de loja.
Um visual limpo, estilo revista, com tons quentes de papel e tipografia nítida, para uma loja polida e confiável.
Tema padrão de fallbackUm tema escuro, ousado e luxuoso, com detalhes em dourado — pensado para parecer empolgante e sofisticado.
Um visual quente e ricamente decorado, inspirado nos mercados tradicionais, com suporte a idiomas escritos da direita para a esquerda.
Um visual sazonal assombrado e festivo — fundos roxo-escuros com destaques em laranja-abóbora brilhante.
Gateways de pagamento
Os 38 gateways automáticos pertencem a plugins — cada um fica na própria pasta plugins/gateway-<slug>/ e se registra no kernel via add_payment_gateway(). Ativar um já basta; nada no despachante do checkout (payment_processor.php) está preso a um gateway específico.
Os 3 métodos manuais são linhas semeadas pelo kernel, com gateway_type = 'manual' e sem código de init/verify para configurar — eles só exibem instruções de pagamento ou um QR code. O plugin manual-gateway-builder permite que um administrador acrescente outros métodos manuais personalizados sem mexer em código.
Alguns gateways (Stripe, Razorpay, Midtrans, Venmo) também registram um hook render para fluxos de checkout que precisam de JS no cliente — a inicialização do Stripe Checkout, ou um SDK do Razorpay/Midtrans/Braintree que precisa de um ID de pedido ou de um token gerado antes no servidor. Todos os outros gateways funcionam sem nenhuma ligação extra com o kernel.
Camadas de API e AJAX
api/v1/— API REST autenticada por JWT para o aplicativo mobile e consumidores externos. Oapi/v1/middleware/*.phpvalida o cabeçalhoAuthorization: Bearer <token>. Os plugins acrescentam os próprios endpoints viaadd_api_route().ajax/— AJAX interno autenticado por cookie de sessão, para o JS da própria loja (carrinho, cupons, notificações). Sem camada de token — depende da sessão PHP configurada peloconnection.php.- A pasta
api/solta na raiz — endpoints diversos e sem versionamento, comogeo_location.php,exchange-rate.phpeofferwall_postback.php.
Aplicativo mobile
O mobile/ é um projeto Capacitor + Ionic separado — um wrapper WebView em volta do site no ar, não um SPA independente nem apenas um consumidor da api/v1. O capacitor.config.ts dele aponta o server.url para o seu domínio. Ele tem o próprio package.json e não é buildado a partir da raiz do projeto:
cd mobile
npm run sync
npm run open:ios
npm run open:androidAtualizações e migrações
Faça um snapshot antes de rodar o database/migration.sql ou qualquer database/migrations/<slug>/up.sql contra um banco de dados em produção:
mysqldump --single-transaction -u<user> -p<pass> <db> > pre-deploy-$(date +%Y%m%d-%H%M%S).sqlA maioria das migrações traz um down.sql correspondente, que reverte só aquela mudança. Algumas poucas, que transformam dados existentes em vez de apenas acrescentar estrutura, trazem um down.sql que documenta por que ele não faz nada — nesses casos, restaure o dump feito antes do deploy se precisar voltar atrás.
Notas de segurança
- Troque as credenciais de administrador semeadas logo depois da importação (veja Instalação).
- O
.env, oconnection.phpe os arquivos de log são bloqueados para acesso HTTP direto pelas regras de.htaccess/ nginx que já vêm no projeto — não remova essas regras. - O conteúdo enviado é servido de um jeito que impede sua execução como PHP, garantido na configuração do servidor web, não na aplicação.
- As credenciais dos gateways de pagamento são configuradas gateway a gateway pelo painel administrativo e ficam armazenadas no servidor — nunca expostas na loja.
Testes
Não existe suíte de PHPUnit. O composer test roda o bin/run-probes.php, que reúne todo arquivo probe_*.php dentro de includes/_probes/ e da pasta _probes/ de cada plugin, executando cada um como subprocesso de CLI e checando o código de saída.
composer test # run every probe
php plugins/<slug>/_probes/probe_*.php # run a single probe directly
php bin/run-probes.php --all # also run destructive probes (skipped by default)Perguntas frequentes
Suporte e recursos
Ainda travado ou precisa de algo que esta página não cobre?