README

vihaya/events is the official PHP SDK for the Vihaya Events platform. Build event listings, attendee registration flows, Razorpay payment verification, ticketing dashboards, Laravel apps, Symfony bundles, WordPress plugins, Drupal modules, Magento extensions, and any PHP 8.1+ backend — all with type-safe readonly models and forward-compatible parsing.

Vihaya is the modern events platform for India — a single stack for event organisers, ticketing, sponsor management, attendee registration, live check-in, and real-time analytics. This package is the fastest way to integrate the Vihaya Events API (https://events.vihaya.app) into any PHP codebase.

What is Vihaya?
Why the Vihaya PHP SDK?
The Vihaya SDK family
Requirements
Installation
Get your Vihaya API key
Quick start
Configuration
Core concepts
Usage guide
Framework integrations
Mega events & sub-events
Razorpay payment flow
API reference
Models
Error handling
Security best practices
FAQ
Keywords
Development
Contributing
License

🇮🇳 What is Vihaya?

Vihaya is an all-in-one events platform for India, built for organisers who run college fests, hackathons, conferences, workshops, meetups, bootcamps, summits, and corporate events. The Vihaya platform provides:

🎟️ Event creation & ticketing with pricing tiers, promo codes, and a hosted checkout.
🏢 Mega events — bundle dozens of sub-events under one parent fest.
💳 Razorpay payments — end-to-end with server-side signature verification.
📋 Custom registration fields — T-shirt size, college, team members, dietary preferences, accommodation.
👥 Attendee management — real-time registrations, broadcasts, CSV exports.
📱 Live check-in with mobile QR scanning.
👩‍🏫 Speakers, agenda, sponsors, FAQs.
📊 Analytics — registrations, revenue, funnel tracking.

This vihaya/events Composer package lets PHP developers embed the Vihaya Events API into Laravel apps, Symfony bundles, WordPress plugins, Drupal modules, Magento 2 extensions, Slim micro-services, CodeIgniter projects, Yii apps, CakePHP apps, and standalone PHP scripts.

Production URL: https://events.vihaya.app · Marketing site: https://vihaya.app · Developer dashboard: https://events.vihaya.app/profile/developer

✨ Why the Vihaya PHP SDK?

🔐 Modern PHP — final readonly model classes (PHP 8.2 features), strict types, named arguments.
🧪 Tested — PHPUnit 10 suite with Guzzle MockHandler. 11 tests, 32 assertions, fully offline.
📦 Slim — only guzzlehttp/guzzle and ext-json as dependencies.
🔄 Forward compatible — every model preserves unknown fields on $model->raw, so the SDK survives API additions without a release.
🧩 PSR-friendly — accepts a Psr\Http\Client\ClientInterface for custom HTTP middleware (logging, tracing, retries).
🎯 Strict typing — every method signature is fully typed; PHPStan level 6 clean.
💳 Razorpay ready — $vihaya->events()->register() → Razorpay → $vihaya->payments()->verify().

🌍 The Vihaya SDK family (7 languages)

Language	Package	Repository	Install
🐘 PHP	`vihaya/events`	Vishnu252005/vihaya-sdk-php	`composer require vihaya/events`
🟨 JavaScript / TypeScript	`vihaya-sdk`	Vishnu252005/vihaya-sdk	`npm install vihaya-sdk`
🐍 Python	`vihaya-events`	Vishnu252005/vihaya-sdk-python	`pip install vihaya-events`
🦫 Go	`vihaya-sdk-go`	Vishnu252005/vihaya-sdk-go	`go get github.com/Vishnu252005/vihaya-sdk-go`
☕ Java	`vihaya-sdk-java`	Vishnu252005/vihaya-sdk-java	JitPack / Gradle / Maven
💎 Ruby	`vihaya-events`	Vishnu252005/vihaya-sdk-ruby	`gem install vihaya-events`
📱 Flutter / Dart	`vihaya_sdk_flutter`	Vishnu252005/vihaya-sdk-flutter	`flutter pub add vihaya_sdk_flutter`

All Vihaya SDKs target the same API base URL (https://events.vihaya.app), authenticate with the same x-api-key header, and expose the same methods.

📋 Requirements

PHP 8.1, 8.2, 8.3, 8.4+
ext-json
guzzlehttp/guzzle ^7.5 (pulled in automatically)

📦 Installation

composer require vihaya/events

Then load Composer's autoloader:

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

Package name: vihaya/events on Packagist. PHP namespace: Vihaya\Events.

🔑 Get your Vihaya API key

Sign up or log in at events.vihaya.app.
Open the Developer Dashboard.
Click Generate API Key and copy the vh_live_... token.
Store it in .env, environment variables, or a secrets manager — never commit it to git.

# .env
VIHAYA_API_KEY=vh_live_xxxxxxxxxxxxxxxxxxxxxxxx

🚀 Quick start

<?php

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

use Vihaya\Events\Vihaya;
use Vihaya\Events\Models\RegisterData;
use Vihaya\Events\Exceptions\VihayaException;

$vihaya = new Vihaya(getenv('VIHAYA_API_KEY'));

try {
    // List events on the authenticated account
    foreach ($vihaya->events()->list() as $event) {
        echo "{$event->title} — {$event->date} @ {$event->location}\n";
    }

    // Fetch full details for one event
    $event = $vihaya->events()->get('evt_8x42j9');

    // Register an attendee
    $result = $vihaya->events()->register(
        $event->id,
        new RegisterData(
            name:  'Anjali Mehta',
            email: 'anjali@example.com',
            phone: '+919820012345',
            customFields: [
                'T-Shirt Size' => 'L',
                'College'      => 'Vihaya Institute',
            ],
        ),
    );

    // For paid events, $result['orderId'] is a Razorpay order ID
    if (isset($result['orderId'])) {
        $vihaya->payments()->verify(
            paymentId: 'pay_O8K2...',
            orderId:   $result['orderId'],
            signature: 'signature_from_razorpay',
        );
    }
} catch (VihayaException $e) {
    fprintf(STDERR, "Vihaya error (%s): %s\n", $e->getStatus() ?? 'n/a', $e->getMessage());
}

⚙️ Configuration

use Vihaya\Events\Vihaya;

$vihaya = new Vihaya(
    apiKey:  getenv('VIHAYA_API_KEY'),
    baseUrl: 'https://events.vihaya.app',  // override for staging
    headers: [
        'X-Trace-Id'       => 'abc123',
        'X-Request-Source' => 'backend',
    ],
    timeout: 60.0,
);

Parameter	Default	Description
`$apiKey`	—	Required. Sent as the `x-api-key` header on every request.
`$baseUrl`	`https://events.vihaya.app`	Override for staging.
`$headers`	`[]`	Extra headers attached to every request.
`$timeout`	`30.0`	Per-request timeout in seconds.
`$httpClient`	new Guzzle	Inject a custom Guzzle client — useful for tests, middleware, retries.

🧭 Core concepts

Events — the root record. Title, description, date, venue, tiers, custom fields, speakers, agenda, sponsors, FAQs, sub-events.
Mega events — parent events containing sub-events. Access via $event->subEvents.
Registrations — free or paid attendee entries with optional custom fields and team members.
Payments — Razorpay orders created during events()->register(), verified via payments()->verify().
API key — vh_live_... token from the developer dashboard.

📚 Usage guide

Fetch a full event

$event = $vihaya->events()->get('evt_8x42j9');

echo "{$event->title}\n";
echo "Mode: {$event->eventMode}  Timezone: {$event->timezone}\n";
echo "Location: {$event->location}\n";

foreach ($event->speakerList ?? [] as $speaker) {
    echo "- {$speaker->name} ({$speaker->role}) @ {$speaker->company}\n";
}

foreach ($event->agendaList ?? [] as $item) {
    echo "[{$item->time}] {$item->title}\n";
}

foreach ($event->sponsors ?? [] as $sponsor) {
    echo "{$sponsor->name} ({$sponsor->tier})\n";
}

foreach ($event->faqs ?? [] as $faq) {
    echo "Q: {$faq->question}\nA: {$faq->answer}\n\n";
}

foreach ($event->specialPrices ?? [] as $tier) {
    echo "  {$tier->name}: ₹{$tier->amount}\n";
}

foreach ($event->customFields ?? [] as $field) {
    $req = $field->required ? 'required' : 'optional';
    echo "  {$field->name} [{$field->type}] {$req}\n";
}

List & filter events

$events = $vihaya->events()->list();

$mega = array_filter($events, fn($e) => $e->eventType === 'megaEvent');
$free = array_filter($events, fn($e) => $e->isFree);
$online = array_filter($events, fn($e) => $e->eventMode === 'online');

Register with tiers, promo codes, and custom fields

use Vihaya\Events\Models\RegisterData;

$result = $vihaya->events()->register('evt_conf_2026', new RegisterData(
    name:  'Priya Raj',
    email: 'priya@example.com',
    phone: '+919820012345',
    tier:  'Early Bird',
    promoCode: 'LAUNCH10',
    customFields: [
        'College'       => 'IIT Bombay',
        'T-Shirt Size'  => 'M',
        'Year of Study' => '3rd',
    ],
));

Register a hackathon team

$result = $vihaya->events()->register('evt_hackathon_2026', [
    'name'     => 'Team Lead',
    'email'    => 'lead@example.com',
    'phone'    => '+919820012345',
    'teamName' => 'Byte Squad',
    'teamMembers' => [
        ['name' => 'Alice', 'email' => 'alice@example.com', 'phone' => '+91...'],
        ['name' => 'Bob',   'email' => 'bob@example.com',   'phone' => '+91...'],
        ['name' => 'Carol', 'email' => 'carol@example.com', 'phone' => '+91...'],
    ],
]);

You can pass a plain array instead of RegisterData — use camelCase keys (teamMembers, customFields, paymentId) on that path.

🎨 Framework integrations

Laravel

// config/services.php
return [
    'vihaya' => [
        'key' => env('VIHAYA_API_KEY'),
    ],
];

// app/Providers/AppServiceProvider.php
use Vihaya\Events\Vihaya;

public function register(): void
{
    $this->app->singleton(Vihaya::class, function () {
        return new Vihaya(config('services.vihaya.key'));
    });
}

// app/Http/Controllers/EventController.php
use Vihaya\Events\Vihaya;
use Vihaya\Events\Models\RegisterData;
use Vihaya\Events\Exceptions\VihayaException;

class EventController extends Controller
{
    public function __construct(private Vihaya $vihaya) {}

    public function index()
    {
        return $this->vihaya->events()->list();
    }

    public function show(string $id)
    {
        return $this->vihaya->events()->get($id);
    }

    public function register(Request $request, string $id)
    {
        try {
            return $this->vihaya->events()->register($id, new RegisterData(
                name:  $request->input('name'),
                email: $request->input('email'),
                phone: $request->input('phone'),
                customFields: $request->input('customFields', []),
            ));
        } catch (VihayaException $e) {
            return response()->json(['error' => $e->getMessage()], $e->getStatus() ?? 500);
        }
    }
}

Symfony

# config/services.yaml
services:
    Vihaya\Events\Vihaya:
        arguments:
            $apiKey: '%env(VIHAYA_API_KEY)%'

// src/Controller/EventController.php
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Annotation\Route;
use Vihaya\Events\Vihaya;

#[Route('/events')]
class EventController
{
    public function __construct(private Vihaya $vihaya) {}

    #[Route('', methods: ['GET'])]
    public function list(): JsonResponse
    {
        return new JsonResponse($this->vihaya->events()->list());
    }
}

WordPress plugin

<?php
/*
Plugin Name: Vihaya Events
*/

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

use Vihaya\Events\Vihaya;

add_shortcode('vihaya_events', function () {
    $vihaya = new Vihaya(get_option('vihaya_api_key'));
    $events = $vihaya->events()->list();
    ob_start();
    foreach ($events as $event) {
        echo "<h3>{$event->title}</h3><p>{$event->date} @ {$event->location}</p>";
    }
    return ob_get_clean();
});

Slim micro-framework

$app->get('/events', function ($request, $response) {
    $vihaya = new Vihaya(getenv('VIHAYA_API_KEY'));
    $events = $vihaya->events()->list();
    $response->getBody()->write(json_encode($events));
    return $response->withHeader('Content-Type', 'application/json');
});

🏢 Mega events & sub-events

$fest = $vihaya->events()->get('evt_mega_fest_2026');

if ($fest->eventType === 'megaEvent') {
    $count = count($fest->subEvents ?? []);
    echo "{$fest->title} — {$count} sub-events\n";

    foreach ($fest->subEvents ?? [] as $sub) {
        $price = $sub->isFree ? 'Free' : "₹{$sub->price}";
        echo "  - {$sub->title} ({$price})\n";

        foreach ($sub->customFields ?? [] as $field) {
            echo "    * {$field->name} [{$field->type}]\n";
        }
    }
}

💳 Razorpay payment flow

Backend — $vihaya->events()->register($id, $data) → Vihaya creates a Razorpay order and returns orderId.
Frontend — launch Razorpay Checkout with that order ID.
Razorpay callback — hands back razorpay_payment_id, razorpay_order_id, razorpay_signature.
Backend — $vihaya->payments()->verify(...) confirms the signature and marks the registration paid.

$result = $vihaya->events()->register('evt_conf_2026', new RegisterData(
    name:  'Attendee',
    email: 'a@example.com',
    phone: '+91...',
));

// Frontend: Razorpay Checkout with $result['orderId'] ...

$vihaya->payments()->verify(
    paymentId: $razorpayPaymentId,
    orderId:   $razorpayOrderId,
    signature: $razorpaySignature,
);

⚠️ Always verify payments on the server. Never trust a signature checked only in the browser.

📖 API reference

`new Vihaya(string $apiKey, ?string $baseUrl = null, array $headers = [], float $timeout = 30.0, ?ClientInterface $httpClient = null)`

Construct a client. Get your API key from the developer dashboard.

`$vihaya->events()->list(): list<Event>`

Returns every event on the authenticated organiser account.

`$vihaya->events()->get(string $eventId): Event`

Fetches full metadata for one event — agenda, speakers, sponsors, FAQs, pricing tiers, custom fields, venue info, and sub-events for mega events.

`$vihaya->events()->register(string $eventId, RegisterData|array $data): array`

Registers an attendee. Pass a RegisterData for type safety, or a plain array (camelCase keys). Returns the API response — orderId for paid events, registrationId for free.

`$vihaya->payments()->verify(string $paymentId, string $orderId, string $signature, ?float $amount = null): array`

Server-side verification of a Razorpay payment signature. Always call from your backend.

🧬 Models

All models are final readonly classes (PHP 8.2+) with a fromArray() factory. Unknown fields are preserved on $model->raw, so the SDK is forward-compatible with new API fields without waiting for a release.

Event — root event with all metadata
Speaker — name, role, company, bio, photoUrl
Sponsor — name, tier, logoUrl, website
AgendaItem — time, title, description, speaker
Contact — name, email, phone
FAQItem — question, answer
CustomField — name, type, required, options
SpecialPrice — name, amount, description
PromoCode — code, discount, discountType
RegisterData — mutable DTO for the register payload

🚨 Error handling

Every API and transport failure surfaces as VihayaException:

use Vihaya\Events\Exceptions\VihayaException;

try {
    $vihaya->events()->get('evt_missing');
} catch (VihayaException $e) {
    $e->getMessage();   // human-readable error from the server
    $e->getStatus();    // HTTP status code, or null for network errors
    $e->getData();      // raw parsed JSON body, if any

    match ($e->getStatus()) {
        404      => error_log('Not found'),
        401, 403 => error_log('Auth error'),
        429      => error_log('Rate limited'),
        default  => error_log('Other'),
    };
}

🛡️ Security best practices

Never hard-code a vh_live_... key in client-side JavaScript or front-end PHP templates.

Use getenv(), $_ENV, Laravel's config()/env(), Symfony's %env()%, Drupal's settings, or a secrets manager.
Call events()->register() and payments()->verify() from backend code only.
Always verify Razorpay signatures server-side.
Rotate keys via the Vihaya developer dashboard if you suspect a leak.
Use separate keys for staging and production.

❓ FAQ

What is Vihaya?

Vihaya is an events platform for India — ticketing, registrations, payments, check-in, analytics, and attendee management. Platform: vihaya.app. Dashboard: events.vihaya.app.

Does the SDK work with Laravel / Symfony / WordPress / Drupal / Magento?

Yes. It's a plain Composer package with PSR-4 autoloading and zero framework coupling. Drop it into any PHP 8.1+ project.

Why does the test suite use Guzzle's MockHandler?

So composer test runs fully offline — no network, no VCR fixtures, no flakiness. CI is fast and deterministic.

A test asserts `49900` but my response shows `49900.0`. Why?

json_encode collapses whole-number floats to integers. The Vihaya server parses both identically, so this is not an SDK bug. Use fractional amounts in tests (e.g., 499.99) or non-strict assertions.

Can I inject my own HTTP client?

Yes — pass anything implementing GuzzleHttp\ClientInterface (or Psr\Http\Client\ClientInterface) as the fifth constructor argument. Useful for adding logging, tracing, retries, or middleware.

Does Vihaya support Razorpay test mode?

Yes — use a test API key from the Vihaya developer dashboard.

🔎 Keywords

vihaya · vihaya sdk · vihaya php · vihaya php sdk · vihaya events php · vihaya/events · vihaya api php · php events api · laravel vihaya · symfony vihaya · wordpress vihaya plugin · drupal vihaya module · magento vihaya · php ticketing sdk · php razorpay events · vihaya razorpay php · events api india php · event management sdk php · composer vihaya · packagist vihaya · events.vihaya.app php · vihaya official php sdk

🛠️ Development

git clone https://github.com/Vishnu252005/vihaya-sdk-php.git
cd vihaya-sdk-php
composer install
composer test       # PHPUnit (offline, MockHandler)
composer lint       # PHPStan level 6
composer format     # php-cs-fixer

The test suite uses Guzzle's MockHandler and makes no real network calls.

🤝 Contributing

Contributions to the Vihaya PHP SDK are very welcome. The project is open source and MIT-licensed.

Fork Vishnu252005/vihaya-sdk-php.
Create a feature branch.
Run composer test, composer lint, and composer format.
Commit, push, and open a Pull Request.

Reporting issues

Found a bug or have a feature request? Open an issue at github.com/Vishnu252005/vihaya-sdk-php/issues.

📄 License

💬 Support

📧 Email: support@vihaya.app
🌐 Website: vihaya.app
🛠️ Dashboard: events.vihaya.app
👨‍💻 Developer docs: events.vihaya.app/profile/developer/docs
📦 Packagist: packagist.org/packages/vihaya/events
🐛 Issues: github.com/Vishnu252005/vihaya-sdk-php/issues

Built with ❤️ by the Vihaya team.

Related Vihaya SDK repositories

PHP: vihaya-sdk-php — you are here
JavaScript / TypeScript: vihaya-sdk
Python: vihaya-sdk-python
Go: vihaya-sdk-go
Java: vihaya-sdk-java
Ruby: vihaya-sdk-ruby
Flutter: vihaya-sdk-flutter

vihaya / events

Maintainers

Package info

Statistics

Security