PHP Google Maps API 類別封裝：零 JavaScript 快速整合

PHP 封裝 Google Maps API v2 類別完整指南

本類別 `phproogleMap` 完整封裝 Google Maps JavaScript API v2，讓 PHP 開發者無需撰寫 JavaScript 即可在網頁嵌入互動地圖，支援標記、資訊視窗、控制項、地址地理編碼等功能。

核心類別結構

class phproogleMap {
    // 私有屬性：API Key、縮放級別、寬高、中心點、地圖類型、標記點、地址標記、控制項、Div ID
    // 魔術方法：__construct, __set, __get, __isset
    // 公有方法：addGoogleMapControl, addMarker, addMarkerAddress, googleJS, drawMap
    // 私有方法：setGoogleMapTypes, noJavascript
}

完整使用範例

<?php
try {
    $map = new phproogleMap();

    // 基本設定
    $map->apiKey = 'YOUR_GOOGLE_API_KEY';     // 必填
    $map->mapZoom = 14;                       // 0-19
    $map->mapWidth = 350;
    $map->mapHeight = 300;
    $map->mapType = 'normal';                 // normal, satellite, hybrid, physical
    $map->mapCenter = [-33.862828, 151.216974]; // [緯度, 經度]
    $map->mapDivID = 'map';

    // 添加經緯度標記
    $map->addMarker(-33.858362, 151.214876, '<h2>雪梨歌劇院</h2><p>文化愛好者天堂</p>');
    $map->addMarker(-33.862828, 151.216974, '<h3>皇家植物園</h3><a href="https://phpro.org">連結</a>');

    // 添加地址標記（自動地理編碼）
    $map->addMarkerAddress('2 Pitt St Sydney NSW Australia', '<h2>總公司</h2>');
    $map->addMarkerAddress('122 Pitt St Sydney NSW Australia', '<h2>工廠</h2>');

    // 添加地圖控制項
    $map->addGoogleMapControl('GMapTypeControl');      // 地圖類型切換
    $map->addGoogleMapControl('GSmallMapControl');     // 縮放/平移控制
    $map->addGoogleMapControl('GOverviewMapControl');  // 概覽圖
} catch (Exception $e) {
    echo $e->getMessage();
}
?>
<html>
<head><?php echo $map->googleJS(); ?></head>
<body><?php echo $map->drawMap(); ?></body>
</html>

主要參數對照表

控制項選項

• GLargeMapControl：大型縮放/平移控制
• GSmallMapControl：小型縮放/平移控制
• GSmallZoomControl：僅縮放控制
• GScaleControl：比例尺
• GMapTypeControl：地圖類型切換
• GHierarchicalMapTypeControl：階層式類型切換
• GOverviewMapControl：縮略概覽圖

重要提醒

1. API 版本：本類別基於 Google Maps API v2，已於 2013 年停止支援。現代專案請使用 API v3（無需 API Key、功能更強）。
2. 地理編碼限制：`addMarkerAddress` 使用即時 `file_get_contents` 呼叫 Google Geocoding API，受限於速率限制，生產環境建議快取或改用 v3 客戶端地理編碼。
3. HTTPS：現代瀏覽器要求 HTTPS，請確保 API 載入網址為 `https://maps.googleapis.com/...`
4. 錯誤處理：類別大量使用 `throw new Exception`，務必包在 `try-catch` 中。

現代替代方案

建議直接使用 Google Maps JavaScript API v3，配合 PHP 傳遞資料給前端（JSON 格式），由前端渲染地圖，架構更清晰、效能更好、功能更完整。