包简介

Real-time WebSocket client library for Forex, Cryptocurrency, and Stock market data from FCS API

README 文档

README

PHP Real-time WebSocket client library for Forex, Cryptocurrency, and Stock market data from FCS API.

This library provides PHP integration with WebSocket for live market data streaming. Uses the JavaScript client library for browser-based real-time updates.

Features

Real-time WebSocket - Live price updates via WebSocket connection
Multi-Market Support - Forex, Crypto, and Stock data in one library
PHP Backend Ready - Easy integration with PHP applications
Auto-Reconnect - Handles WebSocket connection drops automatically
Tab Visibility - Smart disconnect when browser tab is hidden (saves bandwidth)
Heartbeat - Built-in WebSocket keep-alive mechanism

Demo

Use demo API key for testing: fcs_socket_demo

Installation

Composer (Recommended)

composer require fcsapi/websocket

Manual Installation

Download or clone this repository
Include the JavaScript library in your PHP views

<!-- Include JS library from CDN -->
<script src="https://cdn.jsdelivr.net/gh/fcsapi/websocket-php/fcs-client-lib.js"></script>

<!-- Or local file -->
<script src="<?= $baseUrl ?>/fcs-client-lib.js"></script>

Quick Start

Basic PHP Example

<?php
$apiKey = 'YOUR_API_KEY'; // Or use 'fcs_socket_demo' for testing
$symbol = 'BINANCE:BTCUSDT';
$timeframe = '1D';
?>
<!DOCTYPE html>
<html>
<head>
    <title>FCS-API WebSocket Example</title>
    <script src="https://cdn.jsdelivr.net/gh/fcsapi/websocket-php/fcs-client-lib.js"></script>
</head>
<body>
    <div id="price">Loading...</div>

    <script>
        const client = new FCSClient('<?= $apiKey ?>');

        client.onmessage = (data) => {
            if (data.type === 'price' && data.prices) {
                const p = data.prices;
                if (p.mode === 'candle' || p.mode === 'initial') {
                    document.getElementById('price').innerText =
                        `${data.symbol}: $${p.c} (O:${p.o} H:${p.h} L:${p.l})`;
                }
            }
        };

        client.connect().then(() => {
            client.join('<?= $symbol ?>', '<?= $timeframe ?>');
        });
    </script>
</body>
</html>

Laravel Blade Example

{{-- resources/views/realtime.blade.php --}}
@extends('layouts.app')

@section('scripts')
<script src="https://cdn.jsdelivr.net/gh/fcsapi/websocket-php/fcs-client-lib.js"></script>
@endsection

@section('content')
<div id="forex-price">Loading Forex...</div>
<div id="crypto-price">Loading Crypto...</div>

<script>
    const client = new FCSClient('{{ config("services.fcs.api_key") }}');

    client.onmessage = (data) => {
        if (data.type === 'price' && data.prices) {
            const p = data.prices;
            if (p.mode === 'candle' || p.mode === 'initial') {
                if (data.symbol.startsWith('FX:')) {
                    document.getElementById('forex-price').innerText =
                        `${data.symbol}: ${p.c}`;
                } else {
                    document.getElementById('crypto-price').innerText =
                        `${data.symbol}: $${p.c}`;
                }
            }
        }
    };

    client.connect().then(() => {
        client.join('FX:EURUSD', '1D');
        client.join('BINANCE:BTCUSDT', '1D');
    });
</script>
@endsection

CodeIgniter Example

<?php
// app/Controllers/Realtime.php
namespace App\Controllers;

class Realtime extends BaseController
{
    public function index()
    {
        $data = [
            'apiKey' => getenv('FCS_API_KEY') ?: 'fcs_socket_demo',
            'symbols' => ['FX:EURUSD', 'FX:GBPUSD', 'BINANCE:BTCUSDT']
        ];
        return view('realtime', $data);
    }
}

<!-- app/Views/realtime.php -->
<!DOCTYPE html>
<html>
<head>
    <title>Real-time Prices</title>
    <script src="https://cdn.jsdelivr.net/gh/fcsapi/websocket-php/fcs-client-lib.js"></script>
</head>
<body>
    <table id="prices">
        <thead>
            <tr>
                <th>Symbol</th>
                <th>Open</th>
                <th>High</th>
                <th>Low</th>
                <th>Close</th>
                <th>Volume</th>
            </tr>
        </thead>
        <tbody></tbody>
    </table>

    <script>
        const client = new FCSClient('<?= esc($apiKey) ?>');
        const symbols = <?= json_encode($symbols) ?>;

        client.onmessage = (data) => {
            if (data.type === 'price' && data.prices) {
                updatePriceRow(data.symbol, data.prices);
            }
        };

        function updatePriceRow(symbol, p) {
            if (p.mode !== 'candle' && p.mode !== 'initial') return;

            let row = document.getElementById('row-' + symbol.replace(':', '-'));
            if (!row) {
                row = document.createElement('tr');
                row.id = 'row-' + symbol.replace(':', '-');
                document.querySelector('#prices tbody').appendChild(row);
            }
            row.innerHTML = `
                <td>${symbol}</td>
                <td>${p.o}</td>
                <td>${p.h}</td>
                <td>${p.l}</td>
                <td>${p.c}</td>
                <td>${p.v || '-'}</td>
            `;
        }

        client.connect().then(() => {
            symbols.forEach(s => client.join(s, '1D'));
        });
    </script>
</body>
</html>

API Reference

JavaScript Client (Browser-side)

Constructor

const client = new FCSClient(apiKey, url);

Parameter	Type	Default	Description
`apiKey`	string	required	Your FCS API key
`url`	string	`wss://ws-v4.fcsapi.com/ws`	WebSocket server URL (optional)

Methods

`connect()`

Connects to the WebSocket server. Returns a Promise.

client.connect().then(() => {
    console.log('Connected!');
}).catch(err => {
    console.error('Connection failed:', err);
});

`disconnect()`

Manually closes the connection.

client.disconnect();

`join(symbol, timeframe)`

Subscribe to a symbol for real-time updates.

// Forex
client.join('FX:EURUSD', '1m');

// Crypto
client.join('BINANCE:BTCUSDT', '1m');

// Stock
client.join('NASDAQ:AAPL', '1m');

`leave(symbol, timeframe)`

Unsubscribe from a symbol.

client.leave('FX:EURUSD', '1m');

`removeAll()`

Unsubscribe from all symbols.

client.removeAll();

Event Callbacks

Callback	Description
`onconnected`	Fired when connection is established
`onmessage`	Fired when data is received
`onclose`	Fired when connection is closed
`onerror`	Fired when an error occurs
`onreconnect`	Fired when reconnection is successful

client.onconnected = () => console.log('Connected!');
client.onmessage = (data) => console.log('Data:', data);
client.onclose = (event) => console.log('Closed:', event.code);
client.onerror = (err) => console.error('Error:', err);
client.onreconnect = () => console.log('Reconnected!');

Configuration Options

Property	Type	Default	Description
`reconnectDelay`	number	3000	Delay (ms) before reconnection attempt
`reconnectlimit`	number	5	Maximum reconnection attempts
`focusTimeout`	number	3	Minutes before disconnect when tab is hidden (0 = never)

const client = new FCSClient('YOUR_API_KEY');
client.reconnectDelay = 5000;  // 5 seconds
client.reconnectlimit = 10;    // 10 attempts
client.focusTimeout = 5;       // 5 minutes

Message Data Format

The WebSocket sends different message types:

1. Join Confirmation

{
    "type": "message",
    "success": true,
    "message": "Successfully joined room: BINANCE:BTCUSDT_1D_0s",
    "room": "BINANCE:BTCUSDT_1D_0s",
    "symbol": "BTCUSDT",
    "timeframe": "1D",
    "short": "joined_room"
}

2. Profile Data (One-time on join)

{
    "type": "price",
    "symbol": "BINANCE:BTCUSDT",
    "timeframe": "1D",
    "prices": {
        "mode": "profile",
        "profile": {
            "current_session": "market",
            "timezone": "Etc/UTC",
            "pro_name": "BINANCE:BTCUSDT",
            "update_mode": "streaming"
        }
    }
}

3. Initial Candle Data (One-time on join)

{
    "type": "price",
    "symbol": "BINANCE:BTCUSDT",
    "timeframe": "1D",
    "prices": {
        "mode": "initial",
        "t": 1766361600,      // Timestamp (Unix seconds)
        "o": 88658.87,        // Open price
        "h": 90588.23,        // High price
        "l": 87900,           // Low price
        "c": 89962.61,        // Close price
        "v": 0.247            // Volume
    }
}

4. Live Candle Updates (Continuous)

Primary update mode - contains all price data including OHLCV and Ask/Bid.

{
    "type": "price",
    "symbol": "BINANCE:BTCUSDT",
    "timeframe": "1D",
    "prices": {
        "mode": "candle",
        "t": 1766361600,      // Timestamp
        "o": 88658.87,        // Open
        "h": 90588.23,        // High
        "l": 87900,           // Low
        "c": 89962.61,        // Close
        "v": 8192.70,         // Volume
        "a": 89962.62,        // Ask price
        "b": 89962.61         // Bid price
    }
}

5. Ask/Bid Updates

Sent when only Ask/Bid data changes. All values in this message are updated.

{
    "type": "price",
    "symbol": "BINANCE:BTCUSDT",
    "timeframe": "1D",
    "prices": {
        "mode": "askbid",
        "update": 1766411426, // Update timestamp
        "c": 89962.61,        // Close price
        "a": 89962.62,        // Ask price
        "b": 89962.61,        // Bid price
        "t": 1766361600       // Candle timestamp
    }
}

Handling Different Price Modes

client.onmessage = (data) => {
    if (data.type === 'price' && data.prices) {
        const p = data.prices;
        const symbol = data.symbol;

        switch (p.mode) {
            case 'profile':
                console.log(`${symbol} Profile loaded`);
                break;

            case 'initial':
            case 'candle':
                console.log(`${symbol}: O=${p.o} H=${p.h} L=${p.l} C=${p.c} V=${p.v} Ask=${p.a} Bid=${p.b}`);
                break;

            case 'askbid':
                console.log(`${symbol}: Ask=${p.a} Bid=${p.b}`);
                break;
        }
    }
};

Symbol Format

Symbols must include an exchange prefix:

Market	Format	Examples
Forex	`FX:PAIR`	`FX:EURUSD`, `FX:GBPUSD`, `FX:USDJPY`
Crypto	`EXCHANGE:PAIR`	`BINANCE:BTCUSDT`, `BINANCE:ETHUSDT`
Stock	`EXCHANGE:SYMBOL`	`NASDAQ:AAPL`, `NYSE:TSLA`

Timeframes

Timeframe	Description
`1`	1 minute
`5`	5 minutes
`15`	15 minutes
`30`	30 minutes
`1H`	1 hour
`4H`	4 hours
`1D`	1 day
`1W`	1 week
`1M`	1 month

Examples

Check the /examples folder for complete working demos:

forex-example.php - Real-time Forex prices
crypto-example.php - Real-time Cryptocurrency prices
stock-example.php - Real-time Stock prices

PHP Framework Integration

Laravel

Add to your .env:

FCS_API_KEY=your_api_key_here

Add to config/services.php:

'fcs' => [
    'api_key' => env('FCS_API_KEY', 'fcs_socket_demo'),
],

CodeIgniter 4

Add to your .env:

FCS_API_KEY=your_api_key_here

Symfony

Add to your .env:

FCS_API_KEY=your_api_key_here

Browser Tab Visibility

The library automatically handles browser tab visibility to save bandwidth:

When tab is hidden for more than 3 minutes (configurable), connection is closed
When tab becomes visible again, connection is automatically restored
All subscriptions are automatically rejoined after reconnection

Set focusTimeout = 0 to disable this feature:

client.focusTimeout = 0; // Never disconnect when tab hidden

Error Handling

client.onerror = (err) => {
    console.error('WebSocket error:', err);
};

client.onclose = (event) => {
    if (event.code !== 1000) {
        console.error('Unexpected close:', event.code, event.reason);
    }
};

Get API Key

Visit FCS API
Sign up for a free account
Get your API key from the dashboard

Documentation

For complete API documentation, visit:

Support

Email: support@fcsapi.com
Website: fcsapi.com

License

MIT License - see LICENSE file for details.

fcsapi/websocket 适用场景与选型建议

fcsapi/websocket 是一款基于 JavaScript 开发的 Composer 扩展包，目前已累计 1 次下载、GitHub Stars 达 1，最近一次更新时间为 2025 年 12 月 25 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「websocket」「stock」「crypto」「realtime」「bitcoin」「forex」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 fcsapi/websocket 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 fcsapi/websocket 我们能提供哪些服务？

定制开发 / 二次开发

基于 fcsapi/websocket 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 fcsapi/websocket 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

sylius/inventory-bundle 18

Flexible inventory management for Symfony applications.

interjar/module-configurable-child-visibility 29

Magento 2.x Extension to prevent Out of Stock Children being removed from Used Product Collections.

noximo/php-colored-ascii-linechart 199

Pretty line graphs in your console, html or images

maatify/crypto 1

High-level cryptographic primitives and security utilities for Maatify systems including password hashing, reversible encryption, HKDF key derivation, and key rotation.

richardhj/contao-isotope_simple_stockmanagement 7

Simple stock management for Isotope eCommerce

hammer/module-configurable-child-visibility 0

Magento 2.x Extension to prevent Out of Stock Children being removed from Used Product Collections.

fcsapi/websocket

包简介

关键字：

README 文档

README

Features

Demo

Installation

Composer (Recommended)

Manual Installation

Quick Start

Basic PHP Example

Laravel Blade Example

CodeIgniter Example

API Reference

JavaScript Client (Browser-side)

Constructor

Methods

connect()

disconnect()

join(symbol, timeframe)

leave(symbol, timeframe)

removeAll()

Event Callbacks

Configuration Options

Message Data Format

1. Join Confirmation

2. Profile Data (One-time on join)

3. Initial Candle Data (One-time on join)

4. Live Candle Updates (Continuous)

5. Ask/Bid Updates

Handling Different Price Modes

Symbol Format

Timeframes

Examples

PHP Framework Integration

Laravel

CodeIgniter 4

Symfony

Browser Tab Visibility

Error Handling

Get API Key

Documentation

Support

License

fcsapi/websocket 适用场景与选型建议

与 fcsapi/websocket 相关的其它包

统计信息

GitHub 信息

其他信息

`connect()`

`disconnect()`

`join(symbol, timeframe)`

`leave(symbol, timeframe)`

`removeAll()`