PHPackages vietiso/oneguide - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. vietiso/oneguide ActiveLibrary vietiso/oneguide ================ SDK PHP tích hợp với hệ thống OneGuide: đồng bộ tour điều hành, gán hướng dẫn viên, truy vấn danh mục. V0.1.6(1mo ago)014↓66.7%MITPHPPHP >=7.4 Since Jul 17Pushed 1w agoCompare [ Source](https://github.com/tech3-vietiso/oneguide)[ Packagist](https://packagist.org/packages/vietiso/oneguide)[ RSS](/packages/vietiso-oneguide/feed)WikiDiscussions master Synced 1w ago READMEChangelog (9)DependenciesVersions (8)Used By (0) OneGuide SDK ============ [](#oneguide-sdk) SDK PHP giúp tích hợp với hệ thống **OneGuide**: đồng bộ tour điều hành, gán hướng dẫn viên cho tour và truy vấn danh mục (tỉnh/thành...). Yêu cầu ------- [](#yêu-cầu) - PHP 7.4 trở lên. - Extension `curl` và `json` (đi kèm mặc định trong hầu hết bản PHP). Cài đặt ------- [](#cài-đặt) Cài qua Composer: ``` composer require vietiso/oneguide ``` Hoặc nếu dùng trực tiếp từ mã nguồn, chỉ cần nạp autoload của Composer: ``` require 'vendor/autoload.php'; ``` Khởi tạo Client --------------- [](#khởi-tạo-client) Mọi thao tác đều bắt đầu từ một `Client`. Thông tin xác thực (`api_key`, `secret`) do OneGuide cấp, `url` là địa chỉ gốc của API. ``` use Vietiso\OneGuide\Client; $client = new Client([ 'api_key' => 'xxxxxxxxx', 'secret' => 'xxxxxxxxxxxxx', 'url' => 'https://api.oneguide.example/api', ]); ``` Client tự thêm header `X-Api-Key` và `X-Api-Secret` vào mỗi request. Sử dụng ------- [](#sử-dụng) ### 1. Đồng bộ tour điều hành [](#1-đồng-bộ-tour-điều-hành) > **Lưu ý:** đây là tour **đã chuyển sang điều hành** (bắt buộc có ít nhất một điều hành viên), không phải tour chưa chuyển điều hành. Một tour điều hành gồm: thông tin chung, hành trình theo ngày (`Itinerary`), dịch vụ (`Service`), điều hành viên (`Operator`) và thành viên trong đoàn (`Member`). ``` use Vietiso\OneGuide\Tour\Tour; use Vietiso\OneGuide\Tour\TourType; use Vietiso\OneGuide\Tour\Itinerary; use Vietiso\OneGuide\Tour\Operator; use Vietiso\OneGuide\Tour\Member; use Vietiso\OneGuide\Tour\Gender; use Vietiso\OneGuide\Service\Service; use Vietiso\OneGuide\Service\ServiceType; use Vietiso\OneGuide\Service\BookingStatus; // Thông tin chung $tour = new Tour($client); $tour ->setId(111) // ID tour bên hệ thống của bạn (external id) ->setStartDate(new DateTime('2026-01-01')) ->setType(TourType::PRIVATE) // PRIVATE | SIC | OUTBOUND ->setNumberAdult(1) // Phải > 0 ->setCode('HNHP2DAY3NIGHT') ->setTitle('Hà Nội Hải Phòng 2 ngày 3 đêm') ->setNumberDay(3) ->setNumberNight(2); // Hành trình theo ngày (bắt buộc có ít nhất một) $tour->addItinerary( (new Itinerary()) ->setTitle('Ngày 1') ->setDayNumber(1) ->setContent('Đón khách tại sân bay, ăn trưa, tham quan phố cổ.') // Tùy chọn, nội dung chi tiết ->setImage('https://example.com/day1.jpg') // Phải là URL hợp lệ ); // Dịch vụ đi kèm (không bắt buộc; nếu có thì bắt buộc: setId, setTitle, setType, setTourDays) $tour->addService( (new Service()) ->setId(123) // ID dịch vụ bên hệ thống của bạn (bắt buộc) ->setTitle('Khách sạn Mường Thanh') // Bắt buộc ->setType(ServiceType::HOTEL) // Bắt buộc, xem bảng ServiceType bên dưới ->setTourDays([1, 2, 3]) // Bắt buộc, không ngày nào được vượt quá setNumberDay ->setQuantity(2) // Tùy chọn, số lượng (> 0) ->setAmount(1500000) // Tùy chọn, số tiền (>= 0) ->setBookingStatus(BookingStatus::BOOKED) // Tùy chọn, tình trạng đặt với nhà cung cấp: BOOKED (1) | NOT_BOOKED (0) ->setAddress('Hà Nội') // Tùy chọn ->setNote('Phòng đôi, view hồ') // Tùy chọn ->setCompanyName('Mường Thanh Hospitality') // Tùy chọn, thông tin nhà cung cấp ->setCompanyPhone('02438220099') // Tùy chọn ->setCompanyEmail('booking@muongthanh.com') // Tùy chọn ); // Điều hành viên (bắt buộc có ít nhất một) $tour->addOperator( (new Operator()) ->setName('Nguyễn Văn A') ->setEmail('a@example.com') ->setPhone('0325305738') // Tối đa 20 ký tự ->setAvatar('https://example.com/avatar.jpg') ); // Thành viên trong đoàn (không bắt buộc; đồng bộ chung trong sync()) // Nếu có thêm thành viên thì bắt buộc: setId (ID bên hệ thống của bạn) và setFullName. $tour->addMember( (new Member()) ->setId(9001) ->setFullName('Nguyễn Văn A') ->setBirthday(new DateTime('1990-05-20')) // Tùy chọn, đối tượng DateTime ->setPhone('0325305738') // Tùy chọn, tối đa 20 ký tự ->setEmail('a@example.com') // Tùy chọn, phải hợp lệ nếu có ->setPassportNumber('C1234567') // Tùy chọn, số hộ chiếu ->setPassportExpiryDate(new DateTime('2030-12-31')) // Tùy chọn, ngày hết hạn hộ chiếu ->setIdentityCardNumber('001090012345') // Tùy chọn, số CCCD ->setGender(Gender::MALE) // Tùy chọn: MALE | FEMALE | OTHER ->setCountryId(1) // Tùy chọn, ID quốc gia bên OneGuide ->setNote('Trưởng đoàn') // Tùy chọn ); // Validate rồi đẩy lên OneGuide (ném ValidationException nếu dữ liệu sai/thiếu) $tour->sync(); ``` Dịch vụ và thành viên đều được gửi kèm trong chính payload của `sync()` (khóa `services` và `guests`), không có endpoint riêng. Cả hai danh sách này **không bắt buộc** — tour không có dịch vụ/thành viên nào vẫn đồng bộ được (gửi mảng rỗng). Riêng với thành viên, trường tùy chọn nào không set sẽ được lược khỏi payload; với dịch vụ thì trường không set gửi lên `null`. Xem đầy đủ tại [examples/sync-tour.php](examples/sync-tour.php). ### 2. Gán hướng dẫn viên cho tour [](#2-gán-hướng-dẫn-viên-cho-tour) Gán (đồng bộ) danh sách hướng dẫn viên cho một tour đã tồn tại, kèm những ngày mỗi người phụ trách. ``` use Vietiso\OneGuide\Tour\Tour; use Vietiso\OneGuide\Guide\Guide; $tour = new Tour($client); $tour->setId(111); // ID tour cần gán $guide = new Guide('148235149'); // card_number: số thẻ hướng dẫn viên $guide->setEmail('guide@example.com'); // Email bắt buộc & phải hợp lệ $guide->setPhone('0327145495'); // Tham số thứ hai là các ngày trong tour mà hướng dẫn viên phụ trách $tour->addGuide($guide, [1, 2, 3, 4]); $tour->syncGuides(); ``` Xem đầy đủ tại [examples/add-tour-guide.php](examples/add-tour-guide.php). ### 3. Đồng bộ tạm ứng cho hướng dẫn viên [](#3-đồng-bộ-tạm-ứng-cho-hướng-dẫn-viên) Đồng bộ danh sách tạm ứng (chi phí ứng trước) của hướng dẫn viên cho một tour đã tồn tại. Mỗi hướng dẫn viên có thể có nhiều khoản tạm ứng. Các trường **bắt buộc** khi gọi `syncAdvances()`: - `card_number` của hướng dẫn viên (`new Guide(...)`). - Mỗi khoản tạm ứng (`Advance`): `external_expense_id` (`setId`), `expense_code` (`setCode`), `title` (`setTitle`), `tour_service_id` (`setServiceId`) và `amount` (`setAmount`). ``` use Vietiso\OneGuide\Tour\Tour; use Vietiso\OneGuide\Guide\Guide; use Vietiso\OneGuide\Guide\Advance; $tour = new Tour($client); $tour->setId(111); // ID tour cần đồng bộ $guide = new Guide('101153183'); // card_number: số thẻ hướng dẫn viên (bắt buộc) // Thêm một hoặc nhiều khoản tạm ứng cho hướng dẫn viên $guide->addAdvance( (new Advance()) ->setId(1001) // ID tạm ứng bên hệ thống của bạn (bắt buộc) ->setCode('ADV001') // Mã tạm ứng (bắt buộc) ->setTitle('Tạm ứng ăn trưa') // Tiêu đề tạm ứng (bắt buộc) ->setServiceId(222) // ID dịch vụ trong tour (bắt buộc) ->setAmount(5000000) // số tiền tạm ứng (bắt buộc) ->setCurrency('VND') // Tùy chọn, mặc định là VND ->setNote('Tạm ứng đợt 1') // Tùy chọn ); $tour->addGuide($guide); $tour->syncAdvances(); // Ném ValidationException nếu thiếu trường bắt buộc ``` Xem đầy đủ tại [examples/sync-guide-advances.php](examples/sync-guide-advances.php). ### 4. Lấy danh mục có phân trang (tỉnh/thành) [](#4-lấy-danh-mục-có-phân-trang-tỉnhthành) API trả về dữ liệu theo con trỏ (cursor). `list()` trả về một `Collection`; có thể duyệt trực tiếp bằng `foreach` (tự động lấy trang tiếp theo) hoặc lặp thủ công. ``` use Vietiso\OneGuide\Province\Province; $province = new Province($client); // Cách 1 (khuyến nghị): foreach tự lấy hết các trang $provinces = []; foreach ($province->list() as $item) { $provinces[] = $item; } // Cách 2: lặp thủ công bằng con trỏ $provinces = []; $page = $province->list(); $provinces = array_merge($provinces, $page->getItems()); while ($page->hasMore()) { $page = $province->list(null, 10, $page->getNextCursor()); $provinces = array_merge($provinces, $page->getItems()); } ``` Xem đầy đủ tại [examples/get-province.php](examples/get-province.php). Xử lý lỗi --------- [](#xử-lý-lỗi) SDK ném hai loại ngoại lệ, đều kế thừa từ `OneGuideException`: - **`ValidationException`** — dữ liệu không hợp lệ, phát hiện ở phía SDK **trước khi** gửi request (thiếu trường bắt buộc, sai định dạng URL/email, số điện thoại quá dài...). - **`ApiException`** — request thất bại hoặc server trả về mã lỗi (không phải 2xx). Cung cấp thêm `getStatusCode()`, `getErrors()`, `hasErrors()`, `getResponse()`. ``` use Vietiso\OneGuide\Exception\ValidationException; use Vietiso\OneGuide\Exception\ApiException; try { $tour->sync(); } catch (ValidationException $e) { // Dữ liệu sai trước khi gửi echo $e->getMessage(); } catch (ApiException $e) { // Lỗi từ phía server echo $e->getStatusCode() . ': ' . $e->getMessage(); if ($e->hasErrors()) { var_dump($e->getErrors()); } } ``` Hằng số tham chiếu ------------------ [](#hằng-số-tham-chiếu) Loại tour (`TourType`)Giá trị`PRIVATE`1`SIC`2`OUTBOUND`3Loại dịch vụ (`ServiceType`)Giá trịLoại dịch vụ (`ServiceType`)Giá trị`HOTEL` (khách sạn)1`LANDTOUR`8`RESTAURANT` (nhà hàng)2`BOAT` (thuyền)9`CRUISE` (du thuyền)3`SIGHTSEEING_TICKET` (vé thắng cảnh)10`CAR` (xe ô tô)4`BUS`11`VISA`5`TRAIN`12`VOUCHER`6`INSURANCE` (bảo hiểm)13`FLIGHT_TICKET` (vé máy bay)7`OTHER` (dịch vụ khác)99Giới tính (`Gender`)Giá trị`MALE`1`FEMALE`2`OTHER`3Tình trạng đặt dịch vụ với nhà cung cấp (`BookingStatus`)Giá trị`NOT_BOOKED` (chưa đặt)0`BOOKED` (đã đặt)1Ví dụ ----- [](#ví-dụ) Thư mục [examples/](examples/) chứa các ví dụ chạy được kèm chú thích chi tiết: - [sync-tour.php](examples/sync-tour.php) — đẩy tour điều hành đầy đủ (kèm thành viên trong đoàn). - [add-tour-guide.php](examples/add-tour-guide.php) — gán hướng dẫn viên cho tour. - [sync-guide-advances.php](examples/sync-guide-advances.php) — đồng bộ tạm ứng cho hướng dẫn viên. - [get-province.php](examples/get-province.php) — lấy danh sách tỉnh/thành có phân trang. ### Health Score 39 — LowBetter than 84% of packages Maintenance96 Actively maintained with recent releases Popularity8 Limited adoption so far Community9 Small or concentrated contributor base Maturity38 Early-stage or recently created project Bus Factor1 Top contributor holds 94.4% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~2 days Total 7 Last Release 33d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/51852096?v=4)[thuanvp012](/maintainers/thuanvp012)[@thuanvp012](https://github.com/thuanvp012) ![](https://avatars.githubusercontent.com/u/212458059?v=4)[tech3-vietiso](/maintainers/tech3-vietiso)[@tech3-vietiso](https://github.com/tech3-vietiso) --- Top Contributors [![tech3-vietiso](https://avatars.githubusercontent.com/u/212458059?v=4)](https://github.com/tech3-vietiso "tech3-vietiso (17 commits)")[![thuanvp012van](https://avatars.githubusercontent.com/u/51852082?v=4)](https://github.com/thuanvp012van "thuanvp012van (1 commits)") ### Embed Badge ![Health badge](/badges/vietiso-oneguide/health.svg) ``` [![Health](https://phpackages.com/badges/vietiso-oneguide/health.svg)](https://phpackages.com/packages/vietiso-oneguide) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)